프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 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
75 lines
8.1 KiB
Markdown
75 lines
8.1 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`).
|
|
- 문서만 바꾸는지, 코드도 바꾸는지.
|
|
|
|
## 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`다. 지금 코드가 지키는 규칙은 1절 묶음(링크하면 `verify:documentation` 범위에 든다), 앞으로의 설계는 2절, 리뷰·계획·작업 추적은 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`와 그 1절이 링크한 문서, 폴더 링크는 그 폴더 바로 아래 `.md`)의 문서라면:
|
|
- 백틱 안 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 뼈대, 상대 링크). 편집 훅이 실패 줄을 먼저 알려 준다.
|
|
- 1절 묶음 문서를 바꿨으면 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이다. 1절 묶음 문서를 바꿨으면 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`으로 문서를 같이 고친다.
|