프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 CLAUDE.md의 리뷰 기준만 읽고 시작했고, 개선 작업 기준은 main에 들어가지 않은 초안 (브랜치 docs/improvement-manual의 docs/improvement 11개)에만 있었다. 백엔드 docs/work/와 같은 모양으로 README(크기·공통 단계·커밋·보고), playbook 여섯(new-feature, improve, research-design, docs-writing, operate, delegate, 모두 같은 9절 뼈대), reference 일곱(gates, review-criteria, structure, testing, performance, defect-patterns, decisions)과 evidence.md를 둔다. 초안의 장을 나눠 옮긴 표는 evidence.md 1.1절이다. SPEC.md의 공통 완료 기준 9개는 improve.md 5절로 옮겨, 문서 체계 정리가 SPEC.md를 이력으로 옮길 수 있게 한다. 진입 문서에는 지난 리뷰 ID를 쓰지 않고 내용과 날짜로 쓴다. ID는 evidence.md와 결정·결함 패턴 색인에만 둔다. 결함 패턴 번호 P-NN은 결정 번호 꼴과 겹쳐 영역 글자+번호(G·T·C·S·W·B)로 다시 매기고 옛 번호 대응을 evidence.md 4절에 남겼다. 열린 결정 대기는 2026-11-06 리뷰 기준으로 갱신했다. 버린 대안: 초안처럼 docs/improvement/ 장 번호 체계를 유지하기. 백엔드와 진입 경로·검사기가 갈라진다. 위험·한계: 이 커밋만으로는 문서 검사 범위 밖이다. docs/README.md가 이 폴더를 링크하는 커밋부터 verify:documentation이 경로를 본다. cold-read 시험은 하지 않았다. 검증: python3 scripts/check-work-docs.py rc=0(뒤 커밋에서 더함). Refs: design-docs harness/01-harness-design.md 13절, PR #6
8.1 KiB
8.1 KiB
문서 작성 — 매뉴얼과 안내 문서를 쓰고 고친다
이 repo의 문서(매뉴얼, 안내, 운영 문서, 이 작업 매뉴얼)를 쓰거나 고치는 일의 절차다. 문서 체계(위치, 묶음, 언어, 머리 블록)의 정본은 docs/README.md와 design-docs conventions/docs-system.md다. 이 playbook은 그것을 다시 쓰지 않고 쓰는 순서와 검사만 정한다.
1. 언제 쓰나
- 매뉴얼(
docs/manual/), 운영 문서(docs/operations/,docs/runbooks/), 계약 문서(docs/architecture/등docs/README.md1절 묶음), 루트README.md·CHANGELOG.md를 쓰거나 고친다. - 이 작업 매뉴얼(루트
AGENTS.md·CLAUDE.md,docs/work/,.claude/아래 규칙·스킬·서브에이전트 문서)을 고친다. - 코드 동작이 바뀐 변경의 문서 몫은 이 playbook이 아니라 그 변경의 playbook 안에서 같은 커밋으로 한다. 이 playbook의 검사는 그때도 쓴다.
2. 받아야 할 것
- 독자(누가 이 문서만 읽고 무엇을 끝내나)와 목적.
- 바꿀 문서와 그 문서의 묶음(현재 계약 / 목표 설계 / 작업 이력,
docs/README.md). - 문서만 바꾸는지, 코드도 바꾸는지.
3. 크기와 사고 순서
- 오타·깨진 링크·한 문장 정정은 작음이다: 목적 한 줄, 대상 확인, 검증.
- 새 안내 문서나 playbook 하나는 중간이다. 문서 체계(묶음, 언어, 진입 경로)를 바꾸는 일은 큼이다. 소유자 검토가 먼저다.
- 선행 사례: 같은 독자를 둔 이 repo의 문서(
docs/manual/,docs/work/)와, 그 문서를 읽고 일한 기록(보고, cold-read 시험 기록). - 스킬:
technical-writing-best-practices,documentation-and-adrs. 사람이 터미널에서 따라 하는 절차서면writing-practitioner-guides.
4. 절차
- 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다".
- 정본을 찾는다. 규칙이 이미
AGENTS.md,.dependency-cruiser.json,config/ci/gates.json,config/performance/budgets.json, 계약 문서에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞고, 문서를 고친다. - 위치를 정한다. 문서 위치 규칙은
docs/README.md다. 지금 코드가 지키는 규칙은 1절 묶음(링크하면verify:documentation범위에 든다), 앞으로의 설계는 2절, 리뷰·계획·작업 추적은 3절(복사한 프로젝트가 지울 수 있다). 여러 repo나 소유자 운영에 걸친 내용은 design-docs에 둔다. - 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. 문체는 「~한다」다.
- 절차는 한 줄에 한 단계, 동사로 시작한다. 명령·경로·package script·게이트 ID는 실제로 있는 것만 쓴다(
package.json,config/ci/gates.json,ls로 확인). - 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 작업 매뉴얼(1절 둘째 줄의 문서) 본문에는 리뷰 ID·번호만 쓴 결정을 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 evidence.md에 모은다. 다른 문서는 리뷰 ID를 출처로 둘 수 있다(꼴은
MMDD/NN-MM). - 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)는 링크가 아니라 코드 표기로 쓴다.
verify:documentation이 repo 밖 링크를 옆 checkout에서 찾아 기계마다 결과가 달라진다. - 숫자를 복제하지 않는다. 예산·기준선·테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다. 측정값을 꼭 적으면 커밋과 측정일을 붙인다.
verify:documentation범위(docs/README.md와 그 1절이 링크한 문서, 폴더 링크는 그 폴더 바로 아래.md)의 문서라면:- 백틱 안 repo 경로, 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크,
corepack pnpm <script>와 백틱 안<prefix>:<name>꼴의 script,FE-GATE-0NNID가 실제로 있어야 한다. - 기능 제거 드릴(FE-GATE-020)이 문서를 복사한 사본에서도 같은 검사를 돈다. 사본은
scripts/lib/removal-fixture.ts의 목록만 복사한다. 그 목록에 없는 루트 파일을 마크다운 링크로 가리키면 드릴이 실패한다. - 검사를 피하려고 경로를 백틱 밖으로 옮기지 않는다. 검사 약화로 기록된 일이 있다.
- 백틱 안 repo 경로, 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크,
- 그 문서를 읽는 테스트를 찾는다:
git grep -n '<파일 이름>' -- tests scripts. 있으면 그 테스트가 기대하는 문장을 지키고 desktop에서 돌린다. 문서 관련 단위 테스트는tests/unit/documentation-readiness.test.ts,tests/unit/deletable-history-documents.test.ts,tests/unit/changelog-review-ids.test.ts다. - 검사를 돌린다.
- 작업 매뉴얼을 바꿨으면 노트북에서
scripts/verify.sh docs(분량 상한, 본문 이력 ID 0, playbook 뼈대, 상대 링크). 편집 훅이 실패 줄을 먼저 알려 준다. - 1절 묶음 문서를 바꿨으면 desktop에서
scripts/verify.sh script verify:documentation. 짝 백엔드 참조가 "확인 못 함"으로 남으면 그 참조뿐인지 적는다. - 다른 문서의 이력 ID·상대 링크는
python3 scripts/check-work-docs.py --history <경로>,--links <경로>로 본다.
- 작업 매뉴얼을 바꿨으면 노트북에서
- 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다(정본 design-docs
conventions/delegation-loop.md10절). 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다.
playbook을 새로 만들 때의 뼈대(모든 playbook이 같은 제목을 쓴다. 검사 스크립트가 본다): 1. 언제 쓰나 · 2. 받아야 할 것 · 3. 크기와 사고 순서 · 4. 절차 · 5. 완료 기준 · 6. 하지 말 것 · 7. 막혔을 때 · 8. 보고 형식 · 9. 자주 하는 실수(10줄 이하)
5. 완료 기준
- 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다.
- 문서의 명령·경로·script·게이트 ID가 기준 커밋에 실제로 있다. 정본을 복사한 문장이 없다.
- 작업 매뉴얼을 바꿨으면
scripts/verify.sh docs가 rc=0이다. 1절 묶음 문서를 바꿨으면 desktopverify:documentation이 통과했다(로그 경로). - 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다.
6. 하지 말 것
- 정본의 규칙을 문서에 다시 쓰지 않는다. 갈라진 복사본이 된다.
- 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 처리 결과는 리뷰 README에 쓴다. 기록 문서(리뷰, 계획)는 머리 블록만 고친다.
- 소유자 환경 규칙(실행 위치, 세션 도구)을 여러 곳에 쓰지 않는다. operate.md 4.1절과 delegate.md 4.3절에만 둔다.
- 현재 계약 문서가 작업 이력 문서(복사한 프로젝트가 지울 수 있는 것)에 기대게 하지 않는다.
7. 막혔을 때
- 정본끼리 다르게 말하면 어느 쪽도 고르지 않는다. 양쪽 근거를 붙여 README 5절 형식으로 묻는다.
- 같은 시간에 문서 체계를 바꾸는 다른 세션이 있으면 그 세션이 맡은 파일을 고치지 않는다. 필요한 줄은 그 세션에 넘긴다.
8. 보고 형식
README 6절에 더해 적는다: 독자 한 문장, 바꾼 문서와 묶음, 검사(명령 · 실행 위치 · rc), 문서를 읽는 테스트를 찾은 명령과 결과, cold-read나 자가 점검에서 막힌 곳과 고친 것.
9. 자주 하는 실수
- 노트북에 없는 경로(다른 브랜치에만 있는 파일)를 백틱으로 써서
verify:documentation이 실패한다. 기준 커밋에서ls로 확인한다. - 숫자를 문서에 옮겨 적고 다음 변경에서 낡는다. 정본을 가리킨다.
- 지운 기능·스크립트의 이름이 문서에 남는다. 지우는 커밋에서
git grep으로 문서를 같이 고친다.