From 3524d6b00b02803583f57126c0a1ca5521198f8a Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 17:24:28 +0900 Subject: [PATCH 01/20] =?UTF-8?q?docs(work):=20=EC=9E=91=EC=97=85=20?= =?UTF-8?q?=EB=A7=A4=EB=89=B4=EC=96=BC=20docs/work/=EB=A5=BC=20=EB=91=90?= =?UTF-8?q?=EA=B3=A0=20=EA=B0=9C=EC=84=A0=20=EB=A7=A4=EB=89=B4=EC=96=BC=20?= =?UTF-8?q?=EC=B4=88=EC=95=88=EC=9D=84=20=ED=9D=A1=EC=88=98=ED=95=9C?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 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 --- docs/work/README.md | 75 ++++++++++++ docs/work/delegate.md | 124 +++++++++++++++++++ docs/work/docs-writing.md | 74 ++++++++++++ docs/work/evidence.md | 99 +++++++++++++++ docs/work/improve.md | 150 +++++++++++++++++++++++ docs/work/new-feature.md | 77 ++++++++++++ docs/work/operate.md | 98 +++++++++++++++ docs/work/reference/decisions.md | 91 ++++++++++++++ docs/work/reference/defect-patterns.md | 100 +++++++++++++++ docs/work/reference/gates.md | 110 +++++++++++++++++ docs/work/reference/performance.md | 74 ++++++++++++ docs/work/reference/review-criteria.md | 161 +++++++++++++++++++++++++ docs/work/reference/structure.md | 120 ++++++++++++++++++ docs/work/reference/testing.md | 106 ++++++++++++++++ docs/work/research-design.md | 87 +++++++++++++ 15 files changed, 1546 insertions(+) create mode 100644 docs/work/README.md create mode 100644 docs/work/delegate.md create mode 100644 docs/work/docs-writing.md create mode 100644 docs/work/evidence.md create mode 100644 docs/work/improve.md create mode 100644 docs/work/new-feature.md create mode 100644 docs/work/operate.md create mode 100644 docs/work/reference/decisions.md create mode 100644 docs/work/reference/defect-patterns.md create mode 100644 docs/work/reference/gates.md create mode 100644 docs/work/reference/performance.md create mode 100644 docs/work/reference/review-criteria.md create mode 100644 docs/work/reference/structure.md create mode 100644 docs/work/reference/testing.md create mode 100644 docs/work/research-design.md diff --git a/docs/work/README.md b/docs/work/README.md new file mode 100644 index 00000000..cfb47ad4 --- /dev/null +++ b/docs/work/README.md @@ -0,0 +1,75 @@ +# 작업 매뉴얼 + +이 폴더는 이 repo에서 하는 모든 일의 절차서다. 사람과 AI 세션이 같은 절차를 쓴다. +읽는 순서는 하나다: 루트 `AGENTS.md`(지도) → 이 README → 맡은 일의 playbook 하나. Claude Code 세션에서는 루트 `CLAUDE.md`가 `AGENTS.md`를 가져온다. +규칙의 정본은 `AGENTS.md`, `.dependency-cruiser.json`, `config/ci/gates.json`이다. 이 폴더는 규칙을 다시 쓰지 않고, 일하는 순서를 정한다. + +## 1. 어떤 playbook인가 + +| 맡은 일 | playbook | +| --- | --- | +| 새 기능을 만든다(`create:feature`) | [new-feature.md](new-feature.md) | +| 있는 코드를 리뷰·수정·리팩터링·최적화한다. 구조·테스트 구조를 바꾼다 | [improve.md](improve.md) | +| 바꾸기 전에 대안을 비교하고 소유자 결정을 받는다 | [research-design.md](research-design.md) | +| 매뉴얼·안내 문서를 쓰거나 고친다 | [docs-writing.md](docs-writing.md) | +| 게이트를 돌린다, 릴리스한다, 파생 프로젝트에 템플릿 변경을 넘긴다 | [operate.md](operate.md) | +| 큰 일을 나눠 다른 세션에 맡긴다 | [delegate.md](delegate.md) | + +둘에 걸리면 이렇게 고른다. 결정이 먼저 필요하면 research-design이다. 동작이 바뀌는 코드가 있으면 new-feature나 improve다. 문서만 바뀌면 docs-writing이다. + +## 2. 크기 정하기 + +- 크기는 작음·중간·큼 셋이다. 정의와 크기별로 할 단계는 design-docs `conventions/work-thinking-order.md` 2절이 정본이다. +- 요약: 작음은 파일 몇 개·새 결정 없음·되돌리기 쉬움, 중간은 경계 하나(adapter 그룹, 기능 폴더, 문서 폴더) 안의 여러 파일이나 소유자 없이 정할 작은 결정 하나, 큼은 새 체계·아키텍처·공개 계약·소유자 결정이 필요한 일이다. +- brief(작업 지시문)에 크기가 있으면 그대로 한다. 올릴 수는 있고 내릴 수는 없다. 올리면 이유를 보고에 쓴다. brief가 없으면 스스로 정한다. 망설여지면 큰 쪽이다. +- 아래는 파일이 하나여도 큼이다: import 규칙(`.dependency-cruiser.json`), 최상위 `src/` 폴더, adapter 배럴의 공개 표면, 게이트 단계·기준(`config/ci/gates.json`, `config/performance/budgets.json`), 짝 백엔드와 맞춘 계약(`config/contracts/`), 런타임 설정 키, 파생 프로젝트가 따라 고쳐야 하는 변경, 보안 정책. +- 큰 일은 만들기 전에 멈추고 소유자 검토를 받는다([research-design.md](research-design.md)). 소유자가 그 변경을 이미 정했으면(결정 색인 행, 소유자 원문) 그 결정이 소유자 검토다. 출처와 시각을 보고에 적고 만든다. 결정이 다루지 않은 범위만 멈추고 묻는다. + +## 3. 모든 작업의 공통 단계 + +1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다. +2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다. +3. 바뀌는 경계를 찾는다. 위험은 파일 수가 아니라 경계로 정한다: 사용자 데이터(결과 불명 쓰기, 브라우저 저장소), 공개 포트·배럴, merge 게이트, 짝 백엔드 계약을 건드리면 높다. +4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있고, 이 repo의 스킬은 `.claude/skills/`다(`new-feature`, `desktop-gates`). 파일을 바꾸는 일은 직접 하거나 하위 세션에 맡기고, 결과만 받는 일은 서브에이전트에 맡겨도 된다([delegate.md](delegate.md) 4.3절). +5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다. +6. 무거운 실행(pnpm, 게이트, 브라우저, 빌드)은 [operate.md](operate.md) 「실행 위치」대로 `scripts/verify.sh`로 한다. +7. 일이 다른 경계나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절). +8. 완료를 말하기 전에 검증한다(`superpowers:verification-before-completion`). 돌리지 못한 검증은 못 돌렸다고, 이유와 함께 쓴다(꼭 지킬 것 5). + +## 4. 커밋 + +- 커밋·push는 brief가 허용한 것만 그 작업의 자기 브랜치에 한다. 커밋과 push는 따로 허용된다. 커밋만 허용됐으면 push하지 않는다(desktop 검증은 `scripts/verify.sh`가 패치로 옮긴다). +- main 병합, main·다른 브랜치 push, force push, PR 병합은 하지 않는다. 그것은 소유자(또는 소유자가 정한 총괄)가 한다. +- 메시지 형식은 design-docs `conventions/commit-and-pr.md`를 따른다. AI 꼬리말과 자리표시자(`TBD`, `TODO`, 채우지 않은 칸)를 넣지 않는다. 결함 수정은 꼬리말 `Refs:`에 발견 ID를 적는다(형식은 [reference/review-criteria.md](reference/review-criteria.md) 10절). +- 커밋 하나에 논리 변경 하나다. 동작 변경을 위한 리팩터링은 앞 커밋으로 나눈다. 그 작업이 바꾼 파일만 stage한다. + +## 5. 막혔을 때 + +- 소유자만 정할 수 있는 것(공개 계약, 파생 프로젝트 동작, 보안 정책, 게이트 기준, 되돌리기 비싼 선택)은 근거와 권하는 안을 붙여 한 번 묻고, 그 항목만 멈춘다. +- brief를 준 쪽이 있으면 그쪽에 묻는다. 없으면 소유자에게 묻는다. 형식: 항목 · 선택지 · 권하는 안과 이유 · 정할 사람. + +## 6. 보고 + +- 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다. 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다. +- 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다. 숫자(테스트 수, 실패 수, 시간)는 로그에서 옮긴다. +- 착수할 때 예측(p30·p50·p80과 근거)을, 끝 보고 직전에 실측을 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다(형식 `docs/ledger/README.md`). +- 사고 순서 흔적 칸을 둔다(`conventions/work-thinking-order.md` 5절). 다른 세션이 맡긴 일이면 design-docs `conventions/delegation-loop.md` 5절 양식을 쓴다. + +## 7. 필요할 때만 읽는 문서 + +| 문서 | 내용 | +| --- | --- | +| [reference/gates.md](reference/gates.md) | `scripts/verify.sh`, 언제 무엇을 돌리나, merge 가능 판정, CI env, 문서 검사 범위 | +| [reference/review-criteria.md](reference/review-criteria.md) | 결함 정의, 등급, 증거, 28개 관점마다 볼 곳, 리뷰 문서 양식 | +| [reference/structure.md](reference/structure.md) | 폴더·모듈·코드 구조 기준, 바꿀 때 같이 고칠 것 | +| [reference/testing.md](reference/testing.md) | 테스트 위치, 검출력 확인, 가끔 떨어지는 테스트 | +| [reference/performance.md](reference/performance.md) | 예산 세 맥락, 측정 조건, 숫자를 고칠 때 | +| [reference/defect-patterns.md](reference/defect-patterns.md) | 반복해서 나온 결함의 모양과 막는 기준 | +| [reference/decisions.md](reference/decisions.md) | 이미 정한 결정의 색인, 결정 대기 쓰는 법 | +| [evidence.md](evidence.md) | 이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID | + +## 8. 이 폴더를 고칠 때 + +- 분량 상한: 지도(루트 `AGENTS.md`) 40줄, 루트 `CLAUDE.md` 15줄, 이 README 80줄, playbook 150줄, 진입 경로(지도 + 루트 `CLAUDE.md` + README + playbook 하나) 350줄. `reference/`는 상한이 없다. +- 본문에 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 [evidence.md](evidence.md)로 옮긴다. 루트 `AGENTS.md`·`CLAUDE.md`, `.claude/` 아래 문서도 같다. `reference/decisions.md`·`reference/defect-patterns.md`와 리뷰 문서는 ID를 둔다. +- 고친 뒤 `scripts/verify.sh docs`(노트북)와 desktop `scripts/verify.sh script verify:documentation`이 통과해야 한다. 절차는 [docs-writing.md](docs-writing.md)다. diff --git a/docs/work/delegate.md b/docs/work/delegate.md new file mode 100644 index 00000000..e2b80754 --- /dev/null +++ b/docs/work/delegate.md @@ -0,0 +1,124 @@ +# 총괄 — 큰 일을 나눠 다른 세션에 맡긴다 + +총괄 세션이 일을 나누고, brief를 쓰고, 결과를 대조하고, 합치는 절차다. 공용 절차(brief 양식, 보고 양식, 대조, 교훈 정리, 장부, 지표)의 정본은 design-docs `conventions/delegation-loop.md`다. 이 playbook은 그것을 다시 쓰지 않고, 이 repo의 일을 나누는 법만 더한다. + +```text +총괄 + ├─ 리뷰 라운드: 게이트 1회 → 사본 공유 → 영역 리뷰어 → 실험 목록 → 일괄 실행 → README + ├─ 수정 라운드: 영역별 수정 세션(자기 worktree·브랜치) → 통합 브랜치 → merge 단계 + └─ 멈춤 판정 → 마지막 Medium·Low 수정 → 보고 +``` + +## 1. 언제 쓰나 + +- 일이 커서 여러 세션으로 나눠야 할 때: 전체 리뷰, 영역별 수정 묶음, 리뷰와 수정의 반복, 여러 playbook에 걸친 일. +- 세션 하나가 끝까지 할 수 있는 일이면 이 playbook이 아니다. 그 일의 playbook을 쓴다. +- 맡은 쪽(하위 세션)은 이 playbook이 아니라 brief가 가리킨 playbook을 따른다. + +## 2. 받아야 할 것 + +- 소유자의 목표와 이미 정한 결정. 큰 일이면 소유자가 계획을 검토한 시각. +- 결과가 올라갈 브랜치와 그 최신 커밋(기준 커밋). +- 커밋 허용과 자기 브랜치 push 허용(따로 적는다). push 없이도 desktop 검증은 된다(`scripts/verify.sh`가 패치로 옮긴다). main 병합·main push는 소유자가 한다. +- 마감과 보고 받을 방법. + +## 3. 크기와 사고 순서 + +- 크기는 총괄이 정해 brief에 적는다. 정의는 design-docs `conventions/work-thinking-order.md` 2절이다. 큰 일은 하위 세션이 1~5단계와 대안 비교까지만 하고 멈추게 쓴다. 소유자 검토 뒤 만들기를 다시 맡긴다. +- 총괄 자신의 선행 사례는 지난 라운드의 나누는 법이다: 가장 최근 리뷰 README의 영역 표, 「조치」 절, 「오케스트레이터 자신의 실수」 절. +- 스킬: `delegate`(소유자 환경의 실행판)가 있으면 쓴다. 정본과 다르면 정본이 맞다. + +## 4. 절차 + +### 4.1 맡기고 닫는 순서 + +design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 → 나누기(4.2절) → 기준 커밋 → brief → 하위 세션 띄우기 → 보고 대조 → 합치기 → 교훈 정리 → 장부 한 줄 → 소유자 보고. + +이 repo에서 더할 것: + +- 하위 세션은 착수 보고(이해한 것, 모호한 점과 고른 가정, 예측)를 공유 노트에 쓰고 기다리지 않는다. 예측과 실측은 그 세션이 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다. +- brief에 넣을 것: 목표 한 문장과 끝났다고 볼 조건, 기준 커밋·브랜치·worktree, 읽을 정본과 지난 기록의 위치, 하지 말 것(리뷰면 코드 수정, 수정이면 범위 밖 파일·push·PR, 공통으로 짝 백엔드 쓰기), 실행 위치(`scripts/verify.sh`, [operate.md](operate.md) 4.1절), 보고 형식. +- 「이미 아는 것」에는 [reference/decisions.md](reference/decisions.md)의 결정을 **내용으로** 옮긴다. 번호만 쓰지 않는다. +- 결론을 미리 주지 않는다. 총괄이 만든 변경을 리뷰시킬 때는 코드만 주고 결론은 주지 않는다. +- 수정 묶음 brief에는 공통 지시를 넣는다: RED 먼저, 논리 변경 하나에 커밋 하나, 커밋 규칙, AI 꼬리말 금지, `corepack pnpm`, 무거운 실행은 desktop 공유 잠금 아래. 보고의 「새로 가정하는 것」 칸을 요구한다. +- 하위 세션이 결정이 필요한 것을 만나면 총괄에 한 번 묻고 기다린다. 스스로 정하지 않는다. +- 대조할 때: 보고의 명령·테스트 수를 desktop 로그(`/tmp/claude-gates/<로그 이름>/summary.txt`)에서 찾는다. High 이상과 새 P1은 총괄이 코드에서 직접 다시 확인한다. +- 수정 결과의 "고침"을 그대로 믿지 않는다. 다음 리뷰가 ID별로 다시 판정한다. +- 교훈을 보낼 곳: 그 playbook의 「자주 하는 실수」, 코드 결함 모양은 [reference/defect-patterns.md](reference/defect-patterns.md), 거짓 통과는 [reference/gates.md](reference/gates.md) 6절, 근거는 [evidence.md](evidence.md). + +### 4.2 나누는 법 — 이 repo + +영역은 가장 최근 리뷰 README의 영역 표(16개)를 다시 쓴다. 영역 하나에 리뷰어 하나다. + +| 영역 묶음 | 경로 | +| --- | --- | +| adapters(6개 영역) | `src/adapters/<그룹>/`: browser-transfer, browser-files·cache·cross-context, http·state, realtime, storage·kernel, service worker·push | +| contracts, presentation, app core | `src/contracts/`, `src/presentation/`, `src/bootstrap/`·`src/features/`·`src/platform/` | +| 테스트(2개 영역) | `tests/` 빠른 계층, 브라우저·릴리스·규모 | +| guardrails·CI, build·release | `scripts/`, `config/ci/`, `.gitea/`, 공급망·release 경로 | +| 문서, 성능, 구조 | `docs/`·`README.md`, 예산과 실측, 폴더 구조·기능 개발 패턴 | + +**리뷰 중 실행 — 한 번 돌리고 함께 읽는다**(소유자 결정 2026-11-05). + +- 게이트는 총괄이 한 번 돌린다. 리뷰어마다 같은 빌드·테스트를 다시 돌리지 않는다. 영역 리뷰어 16개가 각자 desktop에서 돌려 잠금 줄에 30여 건이 서고 32건을 취소한 일이 있다. +- 추가 실험은 목록으로 모은다. 항목마다 ID, 명령, env, 시간 상한, 필요하면 변이 패치. 같은 명령은 한 번만 돌리고 결과를 함께 쓴다. +- 실험마다 작업 폴더를 되돌린다. 항목 앞뒤로 추적 파일을 기준 커밋으로 되돌리고 추적 안 된 파일을 지운다(`node_modules`는 둔다). +- 작업 폴더 복제본을 늘려 해결하지 않는다. 한 checkout에서 두 실행이 부딪히는 원인은 고정 출력 경로·고정 포트라는 템플릿 결함이다. 복제본은 그 결함을 가린다. + +두 세션이 동시에 만지면 손으로 풀어야 하는 파일이다. 한 세션만 맡기거나, 총괄이 합칠 때 직접 고친다. + +| 파일 | 왜 | +| --- | --- | +| `CHANGELOG.md` | 묶음마다 미출시 절의 같은 줄 근처를 고친다. 마지막에 한 세션이 다시 쓴다 | +| `docs/reviews/<폴더>/README.md` | 범위·판정표·요약·색인·조치는 총괄이 쓴다 | +| `docs/reviews/adapters/INVENTORY.md`, `.dependency-cruiser.json` | adapter·규칙 하나가 모든 그룹에 걸린다 | +| `config/ci/gates.json`, `.gitea/workflows/*`, `package.json`, `pnpm-lock.yaml` | 단계 검사·생성 workflow·lockfile 전체가 바뀐다 | +| `config/performance/budgets.json`, 초기 JS 기준선 기록 | 묶음마다 맞아도 합친 트리에서 낡는다. 합친 끝에서 다시 잰다 | +| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/`, `scripts/hooks/`, `scripts/verify.sh` | 모든 세션이 읽거나 모든 세션에 걸린다 | + +나눌 때 지킬 것: 두 묶음이 같은 파일을 건드리지 않게 나눈다. 묶음마다 그 시점 최신 기준에서 시작한다. 같은 결함을 두 영역이 보면 한 묶음에만 배정한다. 합칠 때 충돌 해결 밖에서 새로 고칠 것이 생기면 병합 커밋에 넣지 않고 따로 커밋한다. + +### 4.3 소유자 환경 + +하위 세션을 띄우는 법, 보고가 총괄에게 전달되는 길, 공유 노트 폴더, 짝 백엔드 일의 경로 같은 규칙은 design-docs `conventions/delegation-loop.md` 11절 한 곳에 있다. 이 repo에서 더할 것: + +- 나누는 기준(소유자 결정 2026-11-07): + - 파일을 바꾸는 위임, 소유자가 열어 보고 멈출 수 있어야 하는 일은 하위 세션(이 playbook)이다. + - 결과만 받는 일(넓은 검색, 구조 리뷰 `arch-reviewer`, desktop에서 앱을 띄워 보는 확인 `verify-app`, 단순화 제안 `code-simplifier`, 영역 리뷰처럼 문서를 커밋하지 않는 리뷰)은 서브에이전트(정의 `.claude/agents/`)다. 서브에이전트는 파일을 고치지 않는다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. + - pnpm·게이트·브라우저는 누가 돌려도 desktop에서다(`scripts/verify.sh`). +- 짝 백엔드 repo는 읽기만 한다. stage·commit·push하지 않는다. +- 공유 노트: 같은 세션 그룹은 repo 밖 공유 노트 폴더에 큰 발견과 인계 메모를 남긴다. 메시지에 길게 붙이지 않는다. 하위 세션은 다른 노트를 먼저 읽는다. +- 이 절은 소유자의 도구에 묶인 규칙이다. 복사한 프로젝트는 이 절과 [operate.md](operate.md) 4.1절만 자기 환경으로 바꾼다. + +## 5. 완료 기준 + +- 하위 세션마다 brief가 양식대로이고 자리표시자가 없다. +- 보고를 diff·커밋·로그와 대조했고 불일치를 셌다. +- 합친 트리에서 merge 단계가 통과했다(desktop 로그). +- 리뷰·수정 반복이면 [improve.md](improve.md) 4.5절 멈춤 기준이 모두 참이다. +- 교훈 정리와 장부 한 줄을 끝냈다. 소유자 보고에 변경 / 확인(명령·결과·커밋) / 남은 문제가 있다. + +## 6. 하지 말 것 + +- 하위 세션의 일을 대신 하지 않는다. 대조에 필요한 읽기와 확인만 직접 한다. +- 보고를 그대로 믿지 않는다. 같은 파일을 두 세션에 맡기지 않는다. +- 하위 세션에 main 병합·main push, force push, 다른 브랜치 push를 허용하지 않는다. +- 영역 리뷰어마다 desktop에서 게이트를 돌리게 하지 않는다(4.2절). + +## 7. 막혔을 때 + +- 소유자만 정할 수 있는 것은 근거와 권하는 안을 붙여 소유자에게 한 번 묻는다. 그 결정에 기대는 묶음만 멈추고 나머지는 계속한다. +- 하위 세션이 묻는 질문에는 답하고, 질문 원문과 "답이 매뉴얼에 있었나"를 적어 둔다. + +## 8. 보고 형식 + +소유자에게는 변경 / 확인 / 남은 문제 세 칸으로 쓴다. 하위 세션 보고 양식과 대조표는 design-docs `conventions/delegation-loop.md` 5·6절이다. 소유자가 이미 아는 외부 일(PR 병합, CI runner 켜기)은 남은 문제와 섞지 않는다. + +## 9. 자주 하는 실수 + +- 게이트 목록을 지난 라운드 목록에서 가져와 merge 게이트를 놓친다. `scripts/verify.sh merge`로 stage 전부를 돌린다. +- 판정 표를 짝 백엔드 문서만으로 정한다. 코드까지 따라간다. +- 다운스트림 파일을 열지 않고 이름으로 추정해 이행 안내를 쓴다. 확인하지 않은 것은 "미확인"으로 쓴다. +- `verify:documentation`을 옆 checkout 없는 임시 worktree에서 그냥 `pnpm`으로 돌려 재설치 대기로 멈춘다. `scripts/verify.sh script verify:documentation`으로 돌린다(설치를 먼저 한다). +- 제거 드릴을 `npm run`으로 돌려 모든 검사가 `Unknown command`로 실패한다. `corepack pnpm`만 쓴다. +- PR을 만들기 전에 그 head 브랜치의 열린·닫힌 PR과 base 상태를 보지 않아 이미 병합된 커밋으로 PR을 또 만든다. Gitea API(`/api/v1/repos///pulls?state=all`)로 먼저 본다. diff --git a/docs/work/docs-writing.md b/docs/work/docs-writing.md new file mode 100644 index 00000000..9a4394d3 --- /dev/null +++ b/docs/work/docs-writing.md @@ -0,0 +1,74 @@ +# 문서 작성 — 매뉴얼과 안내 문서를 쓰고 고친다 + +이 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