cold-read 3회차(수정 세션 넷의 빈틈 9건), 통합·배치·문서 체계·번역 세션이 「매뉴얼에서 답을 못 찾았다」고 적은 곳, 프론트 총괄 교훈 둘, design-docs repo-structure 01·02·03의 「매뉴얼에 넣을 규칙」 중 백엔드 몫이 아직 매뉴얼에 없다. 세션마다 같은 판단을 스스로 다시 했다. 넣은 자리(항목별 표는 PR 본문): - delegate.md: upgrade 안내 「커밋:」 줄은 총괄이 합칠 때 적는다, 두 라운드 연속 결함이면 조사로, 병합 커밋에는 충돌 해결만, 자주 하는 실수 둘(충돌 없음은 merge-tree로, PR 만들기 전 head 브랜치의 PR을 API로). - improve.md: 절차 문서 결함과 대기 결함의 RED 모양, 테스트 Javadoc도 고친다, 그 코드를 지키는 lane 찾기, 두 라운드 연속 결함이면 조사로. - docs-writing.md: 문체·용어·언어 범위(코드 주석 제외), check-docs도 돌린다, 이동 커밋에 참조 수정을 같이, 번역 기준(영어 절 제목, 레지스트리 yaml, 머리말 없는 runbook, MANIFEST는 납품 당시 해시). - operate.md 4.1: zsh 파이프 rc와 자기 실행 멈추기, runner 사실(capacity 1, 12코어·31GB, 잠금 밖), 취약점 DB는 설치가 아니다, 형식은 나누기 전에. - reference/gates.md: 커밋하는 수정의 lockfile, 처음 켜진 lane의 이전 실패, lychee·buf·trivy 공식 이미지, smoke 이미지가 이 트리에서 만들어졌음, 원래 있던 실패 가리기(세 번), 순서 의존 재현, 공유 잠금 기다리기, 증거 실행의 --no-build-cache, 거짓 통과 두 줄(OOM 재시작, 조건 안 set -e), 새 7절 「workflow·검사 스크립트를 더할 때」. - reference/review-criteria.md: 관점 2·4·9·18·20·21·23·26·27의 볼 곳과 결함, Important 예시, leaf 변경 체크리스트(README 다섯 칸, 문서 검사). - reference/decisions.md: brief와 결정 원문이 다르면 원문, 취약점 DB 기본값. - reference/terms.md(새): 영어 그대로 쓰는 말과 「개발 환경」의 뜻. - README.md 2절(최상위 폴더는 큼), new-feature.md(테스트 환경·release/는 leaf 안), docs/ci-cd/template-vs-consumer.md(docs-check·link-check· check-repo-layout은 파생 서비스도 유지), settings-and-runtime 규칙. 버린 대안: 항목마다 따로 커밋(소유자 결정: 매뉴얼 보강은 한 묶음). 위험: 정한 기본값 둘은 소유자 확인 대상이다: 취약점 DB 받기 허용, 병합 커밋에 충돌 해결만. operate.md는 143/150줄, improve.md 144/150줄로 상한에 가깝다. 검증: check-work-docs(진입 경로 최대 269/350), check-docs, unittest 모두 rc=0.
10 KiB
10 KiB
문서 작성 — 매뉴얼과 안내 문서를 쓰고 고친다
읽은 사람이 묻지 않고 그대로 일할 수 있는 문서를 쓰는 절차다. 매뉴얼은 시험하기 전까지 초안이다.
1. 언제 쓰나
docs/work/,docs/manual/, 루트·leafAGENTS.md, 모듈 README, runbook, 안내 문서를 쓰거나 고칠 때.- 이것은 아니다.
- 리뷰 문서 → improve.md(리뷰 양식은 reference/review-criteria.md 10절)
- 설계서·ADR → 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. 절차
- 독자와 목적을 한 문장으로 쓴다: "<누가> 이 문서만 읽고 <무엇을> 끝낸다".
- 정본을 찾는다. 규칙이 이미
AGENTS.md, registry, leafAGENTS.md,docs/web/http-contract.md,docs/registries/에 있으면 다시 쓰지 않고 가리킨다. 정본과 다르면 정본이 맞다. - 위치를 정한다. 문서 위치 규칙은
docs/README.md다. 여러 repo나 소유자 운영에 걸친 내용은 이 repo가 아니라 design-docs에 둔다. - 결론을 먼저 쓴다. 한 문장에 개념 하나, 처음 나온 용어는 그 자리에서 한 줄로 푼다. 흐름이 있으면 화살표 도식을 먼저 둔다. 표는 둘 이상을 비교할 때만 쓴다. 문체는 「~한다」다. 높임 문장은
check-docs.pystyle이 막는다. 용어는 reference/terms.md의 표기를 쓰고, 새 용어를 정하면 거기에 더한다. 언어 규칙(docs/README.md「문서 수명과 언어」)은 문서(.md)에 걸린다. 코드 주석·Javadoc은 그 파일이 쓰는 언어를 따른다. - 절차는 한 줄에 한 단계, 동사로 시작한다. 명령은 실제로 있는 것만 쓴다. 태스크 이름은
src/build.gradle이나 leafbuild.gradle에서, 경로는ls로 확인한다. - 지난 일을 근거로 쓸 때는 날짜, 무엇이 일어났나, 숫자를 한 줄로 쓴다. 리뷰 ID·묶음 이름·번호만 쓴 결정은 매뉴얼 본문에 쓰지 않는다. 걷어낸 ID 중 근거로 남길 것은 어느 문서에서 왔든 evidence.md에 원래 문서·문장과 함께 모은다. 걷어낸 문서 묶음(예:
docs/manual/, 진입 문서)마다 절 하나를 두고, 같은 묶음을 다시 걷어내면 그 절에 표를 더한다. ID가 무엇을 가리키는지는 evidence.md 머리말 「표기」로 찾는다. 번호의 원래 문서가 이 repo에 없으면 그 번호가 가리키는 규칙 이름과 코드 위치를 근거로 적고, 원래 문서가 repo에 없다고 쓴다. - 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와
file:line은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다. - 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다.
- 그 문서를 읽는 테스트가 있는지 찾는다:
grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다(reference/gates.md 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다. brief가 돌릴 lane을 정했으면 그 lane을 돌린다(지도 3절: brief가 먼저다). docs/work/, 루트AGENTS.md·CLAUDE.md,src/**/AGENTS.md,.claude/아래 문서를 바꿨으면python3 scripts/check-work-docs.py를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다. 어느 문서든 바꿨으면python3 scripts/check-docs.py도 돌린다(언어, 머리 블록, 참조, 복사한 숫자, 문서 지도, 상대 링크, 문체).- 리뷰 폴더 README를 만들거나 고쳤으면
python3 scripts/check-review-index.py docs/reviews/<폴더>를 돌린다. - 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는
--links <파일 또는 폴더>(PR에서는 lychee가 다시 본다), 이력 ID는--history <파일 또는 폴더>.- 이력 검사 패턴을 더하면 오탐을 시험한다. 잡아야 할 이력 문장과 잡지 말아야 할 보통 문장을 시험 파일로 만들어
--history로 돌린다.docs/reviews/**밖 전체(git ls-files '*.md' ':!docs/reviews')에도 돌려 새로 걸린 줄을 모두 읽는다. 검사 대상 파일의 오탐은 패턴을 좁혀 없애고, 대상 밖의 오탐은 보고에 적는다. - 기본 검사를 넓히는 커밋은 그 검사가 새로 잡는 문서를 고친 커밋 뒤에 둔다(또는 같은 커밋). 그래야 어느 커밋에서도 기본 모드가 rc=0이다.
- 이력 검사 패턴을 더하면 오탐을 시험한다. 잡아야 할 이력 문장과 잡지 말아야 할 보통 문장을 시험 파일로 만들어
- 파일·폴더를 옮기는 커밋에는 옮긴 경로를 가리키는 참조 수정(문서 링크, 테스트가 읽는 경로)을 같이 넣는다. 그래야 커밋마다 검사가 통과한다. 내용 수정은 다음 커밋으로 나눈다. 같은 이름의 새 파일이 옛 자리에 생기면 git이 이동으로 잡지 못하니 커밋 본문에 옛 이력을 보는 법을 적는다.
- 옮겨 쓰는(번역하는) 문서의 기준:
- 코드·다른 문서가 영어 절 제목으로 인용하는 절은 제목을 「한국어 (English)」로 둔다. 그 제목을 글자로 비교하는 테스트가 있으면 같은 변경에서 고친다.
- 레지스트리 yaml(
docs/registries/)은 값 칸·머리 설명·행별 설명 주석을 한국어로 옮긴다. 출처 줄, 인용, 테스트가 글자로 비교하는 줄은 원문으로 둔다. - 머리말(
docs/runbooks/template.md의 front matter)이 없는 runbook에 머리말을 새로 만들지 않는다.error_codes·severity를 채우는 것은 새 결정이라 그 runbook을 맡은 작업에서 한다. - 납품 묶음의 해시 목록(
MANIFEST.sha256)은 납품 당시 바이트의 해시다(docs/README.md). 머리 블록을 달거나 번역해 지금 바이트와 맞지 않게 돼도 목록을 고치지 않고, 지금 파일을 맞춰 보는 검사로 쓰지 않는다.
- 매뉴얼·playbook·진입 경로를 새로 만들거나 크게 바꿨으면 cold-read 시험을 한다. 정본은 design-docs
conventions/delegation-loop.md10절이다. 혼자 하는 일이면 최소한 자가 점검을 한다: 지도부터 읽어 그 문서만으로 실제 일 하나의 brief를 써 보고, 막힌 곳을 고친다.
playbook을 새로 만들 때의 뼈대 (모든 playbook이 같은 제목을 쓴다. 검사 스크립트가 본다):
1. 언제 쓰나 · 2. 받아야 할 것 · 3. 크기와 사고 순서 · 4. 절차 · 5. 완료 기준 · 6. 하지 말 것 · 7. 막혔을 때 · 8. 보고 형식 · 9. 자주 하는 실수(10줄 이하)
5. 완료 기준
- 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다.
- 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다.
- 정본을 복사한 문장이 없다. 가리키는 줄만 있다.
docs/work/·루트AGENTS.md·CLAUDE.md·src/**/AGENTS.md·.claude/아래 문서를 바꿨으면scripts/check-work-docs.py가 rc=0이다. 어느 문서든scripts/check-docs.py가 rc=0이다.- 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그).
- 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다.
6. 하지 말 것
- 정본의 규칙을 문서에 다시 쓰지 않는다. 갈라진 복사본이 된다.
- 계획서를 나중에 고치지 않는다. 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 된다(
docs/README.md). - 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 처리 결과는 리뷰 README에 쓴다.
- 소유자 환경 규칙(실행 위치, 세션 도구)을 여러 곳에 쓰지 않는다. operate.md 「실행 위치」와 delegate.md 「소유자 환경」에만 둔다.
- 분량 상한을 넘기지 않는다. 넘으면 같은 문서에서 한 줄을 빼거나
reference/로 내린다.
7. 막혔을 때
- 정본끼리 다른 말을 하면 어느 쪽이 맞는지 정하지 않는다. 두 위치와 차이를 적어 묻는다.
- 소유자 파일(전역
~/.claude/CLAUDE.md, 사용자 설정·스킬, design-docs)을 고쳐야 하면 승인을 받고 고친다.
8. 보고 형식
README 6절에 더해 적는다.
- 바꾼 문서와 줄 수, 분량 상한 대비.
- 검사 결과:
check-work-docs.py,check-docs.py,check-review-index.py, 링크 검사, document-contract lane의 rc와 로그 경로. - cold-read 시험이나 자가 점검: 써 본 brief, 막힌 곳, 고친 것.
- 정본과 다른 곳을 찾았으면 그 위치.
9. 자주 하는 실수
- 지난 리뷰 ID로 이유를 대신한다. 내용과 날짜를 쓴다.
- 저장소 밖 문서를 상대 링크로 써서 링크 검사가 실패한다. 코드 표기로 쓴다.
- 없는 태스크 이름이나 옛 경로를 쓴다. 쓰기 전에 빌드 파일과
ls로 확인한다. --history결과 0을 이력이 없다는 증거로 쓴다. 검사는 아는 꼴만 잡는다. 걷어낸 뒤grep -n -e 리뷰 -e 라운드 -e 결정 <파일>로 남은 괄호를 한 번 더 읽고, 못 잡은 꼴은 검사 패턴에 더한다.