문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와 리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이 "이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는 없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지), 커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음). 고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs delegation-loop/02-design.md 4~6·10절): - CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본 AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는 곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던 내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은 reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절. - docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개 (new-feature, improve, research-design, docs-writing, operate, delegate, 모두 같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns, decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고 review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에 나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고, improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다. - improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과 수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난 수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25, +13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다. - 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를 README 4절과 AGENTS.md에 같은 말로 적었다. - 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인 (reference/decisions.md, reference/defect-patterns.md)에만 둔다. - 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md, docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운 CLAUDE.md 「Layer workflow」를 가리키던 줄). 위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라 초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어 docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/ 본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의 성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다. 검증 - python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80, playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄 - python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0 - CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest .guidanceNamesTheArchitectureSourceSetTask가 기대하는 "./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는 이 커밋을 push한 뒤 desktop에서 돌린다
6.8 KiB
6.8 KiB
문서 작성 — 매뉴얼과 안내 문서를 쓰고 고친다
읽은 사람이 묻지 않고 그대로 일할 수 있는 문서를 쓰는 절차다. 매뉴얼은 시험하기 전까지 초안이다.
1. 언제 쓰나
docs/work/,docs/manual/, 루트·leafCLAUDE.md, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때.- 이것은 아니다.
- 리뷰 문서 → improve.md(리뷰 양식은 reference/review-criteria.md 10절)
- 설계서·ADR → research-design.md
- 코드 동작이 바뀌어 문서를 따라 고치는 일 → 그 코드 변경의 playbook(같은 변경에서 고친다)
2. 받아야 할 것
- 독자: 누가, 무엇을 하려고 읽나. 사람인가, 이력 없는 세션인가, 파생 서비스 개발자인가.
- 그 문서가 가리킬 정본: 규칙이 이미 어디에 있나.
- 위치와 분량 상한.
- 시험 방법: cold-read 시험을 누가 하나(보통 맡긴 쪽이 따로 한다).
3. 크기와 사고 순서
- 오타·깨진 링크·한 문장 정정은 작음이다: 목적 한 줄, 대상 확인, 검증.
- 새 안내 문서나 playbook 하나는 중간이다.
- 문서 체계(매뉴얼 구성, 진입 경로)를 바꾸는 일은 큼이다. 소유자 검토가 먼저다.
- 선행 사례: 같은 독자를 둔 이 repo의 문서(
docs/manual/,docs/work/)와, 그 문서를 읽고 일한 기록(보고, cold-read 시험 기록). - 스킬:
technical-writing-best-practices,documentation-and-adrs. 사람이 터미널에서 따라 하는 절차서면writing-practitioner-guides.
4. 절차
- 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다".
- 정본을 찾는다. 규칙이 이미
AGENTS.md, registry, leafCLAUDE.md,docs/web/http-contract.md,docs/registries/에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다. - 위치를 정한다. 문서 위치 규칙은
docs/README.md다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다. - 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다.
- 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은
src/build.gradle이나 leafbuild.gradle에서, 경로는ls로 확인한다. - 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 리뷰 ID·묶음 이름·번호만 쓴 결정은 매뉴얼 본문에 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 어느 문서에서 왔든 evidence.md에 원래 문서·문장과 함께 모은다.
- 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와
file:line은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다. - 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다.
- 그 문서를 읽는 테스트가 있는지 찾는다:
grep -rn '<파일 이름>' src --include=*.java. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다(reference/gates.md 2절). docs/work/나 루트CLAUDE.md를 바꿨으면python3 scripts/check-work-docs.py를 돌린다. 분량 상한, 본문 이력 ID 0, playbook 뼈대, 상대 링크를 본다.- 리뷰 폴더 README를 만들거나 고쳤으면
python3 scripts/check-review-index.py docs/reviews/<폴더>를 돌린다. - 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는
--links <파일 또는 폴더>(PR에서는 lychee가 다시 본다), 이력 ID는--history <파일 또는 폴더>. - 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs
conventions/delegation-loop.md10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다.
playbook을 새로 만들 때의 뼈대 (모든 playbook이 같은 제목을 쓴다. 검사 스크립트가 본다):
1. 언제 쓰나 · 2. 받아야 할 것 · 3. 크기와 사고 순서 · 4. 절차 · 5. 완료 기준 · 6. 하지 말 것 · 7. 막혔을 때 · 8. 보고 형식 · 9. 자주 하는 실수(10줄 이하)
5. 완료 기준
- 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다.
- 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다.
- 정본을 복사한 문장이 없다. 가리키는 줄만 있다.
docs/work/·루트CLAUDE.md를 바꿨으면scripts/check-work-docs.py가 rc=0이다.- 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그).
- 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다.
6. 하지 말 것
- 정본의 규칙을 문서에 다시 쓰지 않는다. 갈라진 복사본이 된다.
- 계획서를 나중에 고치지 않는다. 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 된다(
docs/README.md). - 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 처리 결과는 리뷰 README에 쓴다.
- 소유자 환경 규칙(실행 위치, 세션 도구)을 여러 곳에 쓰지 않는다. operate.md 「실행 위치」와 delegate.md 「소유자 환경」에만 둔다.
- 분량 상한을 넘기지 않는다. 넘으면 같은 문서에서 한 줄을 빼거나
reference/로 내린다.
7. 막혔을 때
- 정본끼리 다른 말을 하면 어느 쪽이 맞는지 정하지 않는다. 두 위치와 차이를 적어 묻는다.
- 소유자 파일(전역
~/.claude/CLAUDE.md, 사용자 설정·스킬, design-docs)을 고쳐야 하면 승인을 받고 고친다.
8. 보고 형식
README 6절에 더해 적는다.
- 바꾼 문서와 줄 수, 분량 상한 대비.
- 검사 결과:
check-work-docs.py,check-review-index.py, 링크 검사, document-contract lane의 rc와 로그 경로. - cold-read 시험이나 자가 점검: 써 본 brief, 막힌 곳, 고친 것.
- 정본과 다른 곳을 찾았으면 그 위치.
9. 자주 하는 실수
- 지난 리뷰 ID로 이유를 대신한다. 내용과 날짜를 쓴다.
- 저장소 밖 문서를 상대 링크로 써서 링크 검사가 실패한다. 코드 표기로 쓴다.
- 없는 태스크 이름이나 옛 경로를 쓴다. 쓰기 전에 빌드 파일과
ls로 확인한다.