Files
clean-architecture-frontend…/docs/work/docs-writing.md
T
DongHyeonka 5757742ed0 docs(work): 하네스 문서를 새 문서 위치와 검사 범위에 맞춘다
문제: 하네스 PR #13이 더한 작업 매뉴얼·규칙은 이 브랜치가 바꾼 문서
체계의 옛 모습을 적는다.
- 옛 경로: `docs/architecture/decisions/`, `docs/superpowers/`, 루트
  `SPEC.md`, 목표 설계였던 `docs/testing/frontend-platform-testing-strategy.md`
- 옛 검사 범위: 「docs/README.md 1절이 링크한 문서, 폴더 링크는 바로 아래
  .md만」. 지금 verify:documentation은 살아 있는 문서 전부를 보고 언어·
  문체·숫자·머리 블록도 본다
- 옛 docs/README.md 절(1절 묶음 / 2절 목표 설계 / 3절 작업 이력)과 README
  절 이름(「Support scope」, 「Updating a copied project」)
- #13의 template-contract-documents 시험은 README 지워도 되는 표를
  `docs/superpowers/` 행으로 찾는데, 그 행은 이제 없다

고른 방법: 그 줄만 새 위치·새 절 이름·새 범위로 고친다(.claude/rules/docs.md,
docs/work의 docs-writing·operate·research-design·reference 다섯,
docs/problem-statement.md). 시험은 `docs/history/` 행으로 표를 찾는다.
docs/work/evidence.md는 백엔드처럼 매뉴얼 규칙의 근거 기록이라 고치지 않고
`HISTORY_HOLDERS`에 넣어 참조·숫자 검사에서 뺀다.

위험: 하네스 문서의 다른 문장은 건드리지 않았다. 하네스 세션이 쓴 뜻을
바꾸지 않으려는 것이다.

검증: 문서 검사 여섯이 0건, `git grep -n -E 'docs/superpowers|architecture/decisions'`가
기록·CHANGELOG·출처 표시 밖에서 0건.
2026-11-11 20:55:32 +09:00

76 lines
8.4 KiB
Markdown

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