dartlab의 운영 체계를 pyproc 크기에 맞게 차용한 것이다(2026-07-11). 규칙은 가능한 한 "본문 + 기계 가드"를 짝짓는다: 본문은 이 트리에, 기계 가드는 .githooks와 tests/run.mjs에 산다.
| 층 | 위치 | 담는 것 | 판정 질문 |
|---|---|---|---|
| 강행규칙 | 루트 CLAUDE.md (로컬 규칙 문서, git 미추적) |
위반 시 즉시 이력 오염·계약 파손이 나는 규칙만, 짧게. 각 규칙은 상세 문서를 가리킨다 | "어기면 즉시 손상인가?" |
| 공개 운영 문서 | docs/ | 외부 기여자·소비자가 읽을 이유가 있는 객관 운영 규칙 | "외부인이 읽을 이유가 있는가?" |
| 로컬 메모리 | 저장소 밖(git 미추적) | 세션 간 약속·행동 규약. 인덱스 1파일 + 토픽 파일, 포인터 원칙(레포에서 도출 가능한 내용 복제 금지) | 위 둘 다 아니오일 때 |
설계·계획·결정 기록은 별도로 mainPlan/이 정본이다.
아이디어
└─ tests/attempts/<카테고리>/ 개념증명. 브라우저 실측으로 졸업 게이트 통과까지
└─ mainPlan/<이니셔티브>/ 졸업한 학습을 모아 PRD(개발 전 문서)로 확정
└─ src/ 본진 구현(레이어 폴더 + 능력 계약)
└─ mainPlan/_done/ 완료 시 이니셔티브 폴더째 이관
- 신규 능력은 src 직행 금지. 반드시
tests/attempts/<카테고리>/에서 시작한다. 규칙: tests/attempts/README.md. - 카테고리는 막무가내로 만들지 않는다. 진짜 질문(가설 + 성공 기준)이 생겼을 때만 개설하고, 개설했으면 그 안에서 파일로 결과를 쌓아 졸업 게이트가 판정날 때까지 운영한다(졸업 또는 명시적 폐기).
- mainPlan은 착수 전 문서다. attempts에서 얻은 실측을 모아 자기충족적 PRD로 만들고, 착수 전 정합성·ROI를 재검한다. 완료·폐기는
mainPlan/_done/<name>/으로 폴더째 이관. 규칙: mainPlan/README.md. - src는 승격된 코드만. 레이어 = 폴더(
runtime/<-capabilities/<-composition/<-session/·processOs/), import는 아래로만, 교차 관심사는 능력 계약 뒤에.
로컬 메모리는 저장소 밖에 살고 git이 추적하지 않는다. 운영 원칙:
- 인덱스 1파일 + 토픽 파일. 인덱스는 라우팅만 하고 본문을 담지 않는다. 토픽 파일은 종류 접두어(feedback/project/reference)로 구분한다.
- 포인터 원칙. 레포 문서·코드·git 이력에서 도출 가능한 내용은 메모리에 복제하지 않는다. 이미 근본 문서가 있으면 포인터만 둔다.
- 중복 자가 점검. 새 항목을 넣기 전 "근본 문서에 있는가?"를 묻고, 중복을 발견하면 근본 문서로 통합하고 메모리를 축약한다.
- 레포가 정본. 메모리는 세션 간 연속성 장치일 뿐, 프로젝트 상태의 정본은 mainPlan 진행 원장이다.
- 폴더 구조 기획이 먼저다. 코드를 쓰기 전에 어느 레이어·어느 폴더에 사는지부터 정한다. 구조가 어색하면 코드를 밀어넣지 말고 구조를 고친다.
- 클린코드 + 잘 정립된 모듈화. 책임별 분리, 공개 표면은
index.js한 곳, deep-path import 금지(소비자는 subpath export만). - 덕지덕지 금지. 특수 케이스·플래그·패치 누적으로 기능을 만들지 않는다. 강함은 쌓아서가 아니라 깎아서 나온다. 붙이기 전에 "이건 구조 문제 아닌가?"를 먼저 묻는다.
- 바닥부터 다진다. 검증 안 된 추측 위에 쌓지 않는다. 실측(브라우저) -> 계약 -> 구현 순서. 계약과 실제가 어긋나면 계약 실태 표에 먼저 기록한다.
- 정공법. 일부러 얇게 만들거나 우회하지 않는다. 막히면 우회 대신 막힌 지점을 기록하고(attempts/원장) 정면으로 푼다.
| 가드 | 위치 | 차단하는 것 |
|---|---|---|
| commit-msg | .githooks/commit-msg |
커밋 메시지의 도구·생성 흔적 |
| pre-commit | .githooks/pre-commit |
스테이징된 *.md/*.js의 em dash(U+2014) |
| pre-push / reference-transaction | .githooks/ |
non-main 브랜치 생성·푸시 |
| 구조 게이트 | tests/run.mjs |
공개 표면·타입 커버리지 누락, em dash, 깨진 상대 링크, attempts/mainPlan 구조 위반 |
| 런타임 게이트 | tests/browser/run.mjs |
공개 표면의 실제 브라우저 동작 회귀(부팅, 리액티브 실행 경계 계약, 스냅샷-fork, map 병렬). headless Chromium 자동 실행, 의존성 0 |
클론 후 git config core.hooksPath .githooks로 훅을 활성화한다.