문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다.
새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰
05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을
수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로
했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는
넓히지 않는다.
고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는
발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계
기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과
코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지
보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006),
리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호
(03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID.
날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다.
문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는
커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음
커밋 — 중간 커밋이 rc=1이 된다.
위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review·
decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews
밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의
실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만
repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은
문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).
검증(트리 41e44de0, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/A-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
lychee 범위 --links rc=0(578파일, 깨짐 0)
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- ./gradlew :adapter:outbound:persistence-mongo:test --tests
'dev.caskeleton.adapter.outbound.mongo.MongoNamespaceContractTest' --rerun
rc=0(3건)
85 lines
7.4 KiB
Markdown
85 lines
7.4 KiB
Markdown
# 문서 작성 — 매뉴얼과 안내 문서를 쓰고 고친다
|
|
|
|
읽은 사람이 묻지 않고 그대로 일할 수 있는 문서를 쓰는 절차다. 매뉴얼은 시험하기 전까지 초안이다.
|
|
|
|
## 1. 언제 쓰나
|
|
|
|
- `docs/work/`, `docs/manual/`, 루트·leaf `CLAUDE.md`, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때.
|
|
- 이것은 아니다.
|
|
- 리뷰 문서 → [improve.md](improve.md)(리뷰 양식은 [reference/review-criteria.md](reference/review-criteria.md) 10절)
|
|
- 설계서·ADR → [research-design.md](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. 절차
|
|
|
|
1. 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다".
|
|
2. 정본을 찾는다. 규칙이 이미 `AGENTS.md`, registry, leaf `CLAUDE.md`, `docs/web/http-contract.md`, `docs/registries/`에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다.
|
|
3. 위치를 정한다. 문서 위치 규칙은 `docs/README.md`다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다.
|
|
4. 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다.
|
|
5. 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은 `src/build.gradle`이나 leaf `build.gradle`에서, 경로는 `ls`로 확인한다.
|
|
6. 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 리뷰 ID·묶음 이름·번호만 쓴 결정은 매뉴얼 본문에 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 어느 문서에서 왔든 [evidence.md](evidence.md)에 원래 문서·문장과 함께 모은다. 번호의 원래 문서가 이 repo에 없으면 그 번호가 가리키는 규칙 이름과 코드 위치를 근거로 적고, 원래 문서가 repo에 없다고 쓴다.
|
|
7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와 `file:line`은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다.
|
|
8. 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다.
|
|
9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다.
|
|
10. `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다.
|
|
11. 리뷰 폴더 README를 만들거나 고쳤으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다.
|
|
12. 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는 `--links <파일 또는 폴더>`(PR에서는 lychee가 다시 본다), 이력 ID는 `--history <파일 또는 폴더>`.
|
|
13. 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs `conventions/delegation-loop.md` 10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다.
|
|
|
|
**playbook을 새로 만들 때의 뼈대** (모든 playbook이 같은 제목을 쓴다. 검사 스크립트가 본다):
|
|
|
|
`1. 언제 쓰나` · `2. 받아야 할 것` · `3. 크기와 사고 순서` · `4. 절차` · `5. 완료 기준` · `6. 하지 말 것` · `7. 막혔을 때` · `8. 보고 형식` · `9. 자주 하는 실수`(10줄 이하)
|
|
|
|
## 5. 완료 기준
|
|
|
|
- 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다.
|
|
- 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다.
|
|
- 정본을 복사한 문장이 없다. 가리키는 줄만 있다.
|
|
- `docs/work/`·루트 `CLAUDE.md`·`AGENTS.md`·`src/**/CLAUDE.md`를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다.
|
|
- 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그).
|
|
- 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다.
|
|
|
|
## 6. 하지 말 것
|
|
|
|
- 정본의 규칙을 문서에 다시 쓰지 않는다. 갈라진 복사본이 된다.
|
|
- 계획서를 나중에 고치지 않는다. 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 된다(`docs/README.md`).
|
|
- 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 처리 결과는 리뷰 README에 쓴다.
|
|
- 소유자 환경 규칙(실행 위치, 세션 도구)을 여러 곳에 쓰지 않는다. [operate.md](operate.md) 「실행 위치」와 [delegate.md](delegate.md) 「소유자 환경」에만 둔다.
|
|
- 분량 상한을 넘기지 않는다. 넘으면 같은 문서에서 한 줄을 빼거나 `reference/`로 내린다.
|
|
|
|
## 7. 막혔을 때
|
|
|
|
- 정본끼리 다른 말을 하면 어느 쪽이 맞는지 정하지 않는다. 두 위치와 차이를 적어 묻는다.
|
|
- 소유자 파일(전역 `~/.claude/CLAUDE.md`, 사용자 설정·스킬, design-docs)을 고쳐야 하면 승인을 받고 고친다.
|
|
|
|
## 8. 보고 형식
|
|
|
|
[README](README.md) 6절에 더해 적는다.
|
|
|
|
- 바꾼 문서와 줄 수, 분량 상한 대비.
|
|
- 검사 결과: `check-work-docs.py`, `check-review-index.py`, 링크 검사, document-contract lane의 rc와 로그 경로.
|
|
- cold-read 시험이나 자가 점검: 써 본 brief, 막힌 곳, 고친 것.
|
|
- 정본과 다른 곳을 찾았으면 그 위치.
|
|
|
|
## 9. 자주 하는 실수
|
|
|
|
- 지난 리뷰 ID로 이유를 대신한다. 내용과 날짜를 쓴다.
|
|
- 저장소 밖 문서를 상대 링크로 써서 링크 검사가 실패한다. 코드 표기로 쓴다.
|
|
- 없는 태스크 이름이나 옛 경로를 쓴다. 쓰기 전에 빌드 파일과 `ls`로 확인한다.
|
|
- `--history` 결과 0을 이력이 없다는 증거로 쓴다. 검사는 아는 꼴만 잡는다. 걷어낸 뒤 `grep -n -e 리뷰 -e 라운드 -e 결정 <파일>`로 남은 괄호를 한 번 더 읽고, 못 잡은 꼴은 검사 패턴에 더한다.
|