Files
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

8.4 KiB

문서 작성 — 매뉴얼과 안내 문서를 쓰고 고친다

이 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에 모은다. 다른 문서는 리뷰 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 4.1절과 delegate.md 4.3절에만 둔다.
  • 현재 계약 문서가 작업 이력 문서(복사한 프로젝트가 지울 수 있는 것)에 기대게 하지 않는다.

7. 막혔을 때

  • 정본끼리 다르게 말하면 어느 쪽도 고르지 않는다. 양쪽 근거를 붙여 README 5절 형식으로 묻는다.
  • 같은 시간에 문서 체계를 바꾸는 다른 세션이 있으면 그 세션이 맡은 파일을 고치지 않는다. 필요한 줄은 그 세션에 넘긴다.

8. 보고 형식

README 6절에 더해 적는다: 독자 한 문장, 바꾼 문서와 묶음, 검사(명령 · 실행 위치 · rc), 문서를 읽는 테스트를 찾은 명령과 결과, cold-read나 자가 점검에서 막힌 곳과 고친 것.

9. 자주 하는 실수

  • 노트북에 없는 경로(다른 브랜치에만 있는 파일)를 백틱으로 써서 verify:documentation이 실패한다. 기준 커밋에서 ls로 확인한다.
  • 숫자를 문서에 옮겨 적고 다음 변경에서 낡는다. 정본을 가리킨다.
  • 지운 기능·스크립트의 이름이 문서에 남는다. 지우는 커밋에서 git grep으로 문서를 같이 고친다.