docs(work): cold-read 시험에서 막힌 곳과 사실과 다른 곳을 고친다

이 대화를 모르는 서브에이전트에게 AGENTS.md부터 읽혀 두 일(새 기능
만들기, diff 리뷰)의 절차를 쓰게 했다. 막힌 곳 16, 사실과 다른 곳 5가
나왔다. 고친 것:

- new-feature: 생성·기준선 다시 쓰기를 desktop에서 하고 --apply-back으로
  받는다. FE-GATE-020은 제품 기능을 지우지 않으므로 그 기능의 제거
  드릴을 따로 돌린다(사실과 달랐다). 생성 명령이 만드는 첫 context는
  중간이다. 새 기능은 FE-GATE-026도 돌린다. 매뉴얼 예시 이름이 오면
  묻는다. 초기 JS 기록의 파일을 적는다.
- gates·improve·AGENTS: FE-GATE-013 결정 대기 동안의 merge 판정 문구,
  PR·diff 리뷰도 merge 단계 전부를 돌린다, diff 리뷰의 base·head 규칙과
  ID 체계와 둘 곳, 라운드 세는 법, "빠른 게이트 8개"를 "검사 8개
  (package script)"로.
- review-criteria: 발견 한 개의 칸(가이드 36.3절 줄임)과 통제 M0~M4·
  증거 E0~E4의 뜻을 옮긴다. 가이드 없이 판정할 수 있다는 문장을 맞춘다.
- README·CLAUDE·decisions·rules/docs·skills: 최근 리뷰 README의 실제 절
  이름, 사고 순서 흔적의 여섯 칸과 design-docs 위치, 보고 칸과 말투의
  정본, `docs/work/README.md`를 가리키게, 리뷰 README 조치 절 예외,
  스킬의 새 명령 모양.

고치지 않은 것: 세션에 주입된 옛 CLAUDE.md(시험 세션이 이 브랜치 전에
시작했다).

검증: scripts/verify.sh docs rc=0, scripts/verify.sh hooks 통과.
This commit is contained in:
DongHyeonka
2026-11-08 17:53:36 +09:00
parent c50da34712
commit 18ea5e939b
13 changed files with 66 additions and 40 deletions
+1 -1
View File
@@ -6,7 +6,7 @@ paths:
# 문서를 고칠 때
- 문서 위치·묶음·언어 규칙은 `docs/README.md`, 쓰는 절차는 `docs/work/docs-writing.md`다.
- 기록 문서(`docs/reviews/`, `docs/history/`, `docs/superpowers/`, 결정 기록)는 머리 블록만 고친다. 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다.
- 기록 문서(`docs/reviews/`, `docs/history/`, `docs/superpowers/`, 결정 기록)는 머리 블록만 고친다. 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 예외는 그 라운드를 맡은 총괄이 리뷰 README에 「조치」 절(과 그 아래 diff 리뷰 절)을 더하는 것이다.
- 진입 문서(루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/` 아래 문서) 본문에는 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 `docs/work/evidence.md`로 옮긴다. 편집 훅이 `scripts/check-work-docs.py`의 실패 줄을 먼저 알려 준다.
- `docs/README.md` 1절이 링크한 문서(루트 `AGENTS.md`, `docs/work/` 포함)는 `verify:documentation`이 백틱 경로·명령 경로·마크다운 링크·package script·FE-GATE ID를 본다. 있는 것만 쓴다. 검사를 피하려고 백틱을 빼지 않는다. 기능 제거 드릴의 문서 사본은 `scripts/lib/removal-fixture.ts`의 목록만 복사하니, 그 목록 밖 루트 파일을 마크다운 링크로 가리키지 않는다.
- repo 밖 문서(design-docs 등)는 링크가 아니라 코드 표기로 쓴다.
+3 -1
View File
@@ -13,7 +13,9 @@ description: 이 프론트 repo에서 pnpm·게이트·테스트·빌드·브라
- 단계: `scripts/verify.sh merge --log <작업 이름>`
- 게이트 하나: `scripts/verify.sh gate FE-GATE-005 --log <작업 이름>`
- 게이트의 명령을 끝까지: `scripts/verify.sh parts FE-GATE-013 --log <작업 이름>`
- package script: `scripts/verify.sh script verify:documentation test:unit --log <작업 이름>`
- package script: `scripts/verify.sh script verify:documentation test:unit --log <작업 이름>`, 인자는 `--` 뒤에(script 하나일 때만)
- 명령 하나·한 테스트 파일: `scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>`
- 파일을 만드는 명령이면 `--apply-back`으로 결과를 노트북 작업 트리에 받는다. 리뷰용 산출물 사본은 `VERIFY_SNAPSHOT=1`.
- 먼저 무엇을 돌릴지만 보려면 `--dry-run`.
4. 스크립트가 하는 일: 지금 트리를 패치로 보내고, desktop 공유 checkout에서 새 worktree를 만들어 같은 트리인지 해시로 보고, 깨끗한 커밋 하나로 만들어 오프라인 설치 뒤 `flock /tmp/claude-gates/heavy.lock` 아래 CI env(`CI=true` 등)로 돌린다. 공유 checkout의 브랜치와 stash는 건드리지 않는다. push하지 않는다.
5. 결과를 읽는다: desktop `/tmp/claude-gates/<작업 이름>/summary.txt`(첫 줄이 트리 해시), 게이트별 로그, `gate-artifacts/`, `status-after.txt`(비어 있어야 한다).
+3 -3
View File
@@ -9,11 +9,11 @@ description: 이 프론트 템플릿(또는 복사한 프로젝트)에 새 기
1. `docs/work/README.md`, `docs/work/new-feature.md`, `docs/manual/README.md`를 읽고 크기를 정한다. 새 context, 기능 폴더 밖 파일 수정, 짝 백엔드와 새 계약, 예산 상향은 큼이다. 큼이면 만들기 전에 `docs/work/research-design.md`대로 소유자 검토를 받는다.
2. 받을 것을 확인한다: 기능 ID(케밥, 40자 이하), context, 짝 백엔드 경로와 작성 API 유무(`--with-create`), 재전송될 수 있는 쓰기인지(`--keyed`), 계약 패키지 신원. 백엔드 쪽 사실이 brief에 없으면 묻는다.
3. 뼈대: `corepack pnpm create:feature <id> [--context <id>] [--with-create [--keyed]]`. node가 필요하니 desktop이나 노트북의 깨끗한 복제본에서 만든다. 출력의 `Next:` 목록을 보고에 옮긴다.
3. 뼈대: desktop에서 만들고 파일을 돌려받는다: `scripts/verify.sh script create:feature --apply-back -- <id> [--context <id>] [--with-create [--keyed]]`. 출력(로그 폴더의 `create_feature.log`)의 `Next:` 목록을 보고에 옮긴다. 매뉴얼 예시 이름이 기능 ID로 오면 묻는다.
4. `docs/manual/01-add-a-feature.md` 2~10단계로 채운다. 막히면 02 결정표, 폴더 밖 파일은 03, 짝 백엔드 인증은 04, 오류 메시지는 `docs/manual/reference/errors.md`.
5. 동작은 테스트를 먼저 쓴다(`tests/features/<id>/`, 규칙은 `.claude/rules/tests.md`). 결과 불명 쓰기와 재전송 입구는 02 결정표 3·4절.
6. 편집 훅의 경계 알림(N3)이 나오면 그 자리에서 고친다. 기능끼리 import하지 않는다.
7. 초기 JS 기록은 `Next:`의 명령으로 다시 쓰고 같은 커밋에 넣는다. 예산을 넘으면 올리지 말고 멈추고 묻는다.
8. desktop에서 `scripts/verify.sh merge --log <기능 id>`(스킬 `desktop-gates`). 라우트 로딩을 바꿨으면 `scripts/verify.sh gate FE-GATE-026`도.
7. 초기 JS 기록은 `Next:`의 명령을 desktop에서 돌려 받는다(`scripts/verify.sh exec --apply-back -- node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`). 같은 커밋에 넣는다. 예산을 넘으면 올리지 말고 멈추고 묻는다.
8. desktop에서 `scripts/verify.sh merge --log <기능 id>`(스킬 `desktop-gates`), `scripts/verify.sh gate FE-GATE-026`, 그리고 이 기능의 제거 드릴 `scripts/verify.sh script test:sample-removal -- --feature=<id>`.
9. 결과를 보고 싶으면 서브에이전트 `arch-reviewer`(경계 리뷰)와 `verify-app`(desktop에서 앱을 띄워 그 라우트를 연다)에 맡긴다.
10. `docs/work/new-feature.md` 8절 형식으로 보고한다.
+1 -1
View File
@@ -25,7 +25,7 @@
## 검증
- 진입점은 `scripts/verify.sh <단계>`다. 단계는 `config/ci/gates.json`의 stage id(`merge` 등), 게이트 하나는 `scripts/verify.sh gate FE-GATE-005`(안에서 `corepack pnpm ci:gate FE-GATE-005`). pnpm 단계는 desktop으로 옮겨 돈다.
- "merge 가능"은 merge 단계 게이트 전부를 `CI=true`로 돌려 통과한 것이다. 골라 돌린 결과로 말하지 않는다.
- "merge 가능"은 merge 단계 게이트 전부를 `CI=true`로 돌려 통과한 것이다. 골라 돌린 결과로 말하지 않는다. desktop의 FE-GATE-013은 `docs/work/reference/gates.md` 3절 문구로 적는다.
- 문서·지침을 고쳤으면 `scripts/verify.sh docs`(노트북).
## 일하는 방식
+1 -1
View File
@@ -7,4 +7,4 @@
`claude plugin marketplace add https://git.learn.hyeonworks.com/donghyeon.kang/claude-harness.git --scope project`
`claude plugin install harness@claude-harness --scope project`
- 경로별 규칙은 `.claude/rules/`, 스킬은 `.claude/skills/`, 서브에이전트(읽기 전용)는 `.claude/agents/`다.
- 리뷰 기준은 `docs/work/reference/review-criteria.md`, 절차는 `docs/work/improve.md` 4.1절이다. 세션 규칙은 `docs/work/delegate.md` 4.3절, 보고 형식은 소유자 전역 설정이다.
- 리뷰 기준은 `docs/work/reference/review-criteria.md`, 절차는 `docs/work/improve.md` 4.1절이다. 세션 규칙은 `docs/work/delegate.md` 4.3절이다. 보고 칸은 `docs/work/README.md` 6절, 말투와 길이는 소유자 전역 설정을 따른다.
+4 -4
View File
@@ -19,7 +19,7 @@
## 2. 크기 정하기
- 크기는 작음·중간·큼 셋이다. 정의와 크기별로 할 단계는 design-docs `conventions/work-thinking-order.md` 2절이 정본이다.
- 크기는 작음·중간·큼 셋이다. 정의와 크기별로 할 단계는 design-docs(이 repo 옆 checkout `desktop-server-git/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/`), 런타임 설정 키, 파생 프로젝트가 따라 고쳐야 하는 변경, 보안 정책.
@@ -28,7 +28,7 @@
## 3. 모든 작업의 공통 단계
1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다.
2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다.
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을 쓰지 않는다.
@@ -40,7 +40,7 @@
- 커밋·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절).
- 메시지 형식은 design-docs `conventions/commit-and-pr.md`를 따른다. AI 꼬리말과 자리표시자(`TBD`, `TODO`, 채우지 않은 칸)를 넣지 않는다. 결함 수정은 꼬리말 `Refs:`에 발견 ID를 적는다(형식은 [reference/review-criteria.md](reference/review-criteria.md) 11절).
- 커밋 하나에 논리 변경 하나다. 동작 변경을 위한 리팩터링은 앞 커밋으로 나눈다. 그 작업이 바꾼 파일만 stage한다.
## 5. 막혔을 때
@@ -53,7 +53,7 @@
- 맨 앞에 결과(완료 / 부분 / 못 함)와 브랜치·커밋을 쓴다. 그다음 변경, 확인(명령 · 실행 위치 · 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절 양식을 쓴다.
- 사고 순서 흔적 칸(목적·선행 사례·방법·필요한 정보·격차·만들고 시험 여섯 줄, 생략한 단계는 이유)을 둔다(design-docs `conventions/work-thinking-order.md` 5절). 다른 세션이 맡긴 일이면 design-docs `conventions/delegation-loop.md` 5절 양식을 쓴다.
## 7. 필요할 때만 읽는 문서
+1 -1
View File
@@ -60,7 +60,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
**리뷰 중 실행 — 한 번 돌리고 함께 읽는다**(소유자 결정 2026-11-05).
- 게이트는 총괄이 한 번 돌린다. 리뷰어마다 같은 빌드·테스트를 다시 돌리지 않는다. 영역 리뷰어 16개가 각자 desktop에서 돌려 잠금 줄에 30여 건이 서고 32건을 취소한 일이 있다.
- 게이트는 총괄이 `VERIFY_SNAPSHOT=1 scripts/verify.sh merge`로 한 번 돌리고, 리뷰어에게 desktop 로그 폴더와 `snapshot/` 경로를 준다. 리뷰어마다 같은 빌드·테스트를 다시 돌리지 않는다. 영역 리뷰어 16개가 각자 desktop에서 돌려 잠금 줄에 30여 건이 서고 32건을 취소한 일이 있다.
- 추가 실험은 목록으로 모은다. 항목마다 ID, 명령, env, 시간 상한, 필요하면 변이 패치. 같은 명령은 한 번만 돌리고 결과를 함께 쓴다.
- 실험마다 작업 폴더를 되돌린다. 항목 앞뒤로 추적 파일을 기준 커밋으로 되돌리고 추적 안 된 파일을 지운다(`node_modules`는 둔다).
- 작업 폴더 복제본을 늘려 해결하지 않는다. 한 checkout에서 두 실행이 부딪히는 원인은 고정 출력 경로·고정 포트라는 템플릿 결함이다. 복제본은 그 결함을 가린다.
+8 -8
View File
@@ -42,16 +42,16 @@
### 4.1 리뷰
1. 범위를 고정한다: 기준 커밋, 브랜치, 확인 시점, 노트북 worktree와 desktop이 깨끗한지. 전체 리뷰면 리뷰 가이드 0.1절 전제 표를 채운다. 이 repo의 고정 전제는 루트 `AGENTS.md` 첫 문단과 꼭 지킬 것 1·2다. 요청량·데이터량 목표가 없으니 그 칸은 "기능 수 증가 축과 번들·lab 예산으로 판정"으로 적는다.
2. 게이트를 한 번 돌린다: `scripts/verify.sh merge`와 `scripts/verify.sh documentation`. 손으로 적은 명령 목록을 돌리지 않는다(merge 게이트 일부가 빠진 사건이 있다).
3. 결과를 함께 읽는다. 게이트 로그와 `artifacts/`를 읽기 전용 사본으로 떠 두고 모든 리뷰어가 그 사본을 읽는다. 리뷰어마다 다시 돌리지 않는다([delegate.md](delegate.md) 4.2절).
2. 게이트를 한 번 돌린다: `VERIFY_SNAPSHOT=1 scripts/verify.sh merge`와 `scripts/verify.sh documentation`. 손으로 적은 명령 목록을 돌리지 않는다(merge 게이트 일부가 빠진 사건이 있다).
3. 결과를 함께 읽는다. desktop 로그 폴더(`/tmp/claude-gates/<로그 이름>/`)의 게이트 로그와 `snapshot/`(artifacts·dist·test-results 사본)을 모든 리뷰어가 읽는다. 리뷰어마다 다시 돌리지 않는다([delegate.md](delegate.md) 4.2절).
4. 영역을 나눈다. 가장 최근 `docs/reviews/*-maturity-review/README.md`의 영역 표를 다시 쓴다. 영역마다 서브에이전트 하나(결과만 받음) 또는 하위 세션 하나(문서를 커밋함).
5. 영역 문서는 「지난 발견 재판정」부터 쓴다. 지난 라운드가 "고침"이라 한 것도 코드로 다시 본다. 코드는 들어왔지만 완료 기준 실행이 없으면 "일부"다.
6. 더 필요한 실험은 목록으로 낸다(ID, 명령, env, 시간 상한, 변이 패치). 총괄이 모아 같은 명령은 한 번만, 실험마다 작업 폴더를 되돌리며 일괄로 돌린다.
7. 발견을 [reference/review-criteria.md](reference/review-criteria.md) 양식으로 적는다. 같은 결함을 두 영역이 적으면 색인에서 하나로 합치고 「합친 중복」 표에 남긴다.
8. 총괄이 High 이상과 새 P1을 코드에서 직접 다시 읽거나 실행해 확인하고, 재확인 칸에 그 사실을 적는다.
9. README에 범위, 28개 관점 판정표, 최종 요약, 발견 색인을 쓴다(양식 review-criteria.md 9절). 총괄 자신의 실수도 적는다.
9. README에 범위, 28개 관점 판정표, 최종 요약, 발견 색인을 쓴다(양식 review-criteria.md 7절). 총괄 자신의 실수도 적는다.
- PR·diff 리뷰는 2~4단계를 줄인다. 바뀐 파일의 영역만 읽고 그 diff가 건드린 게이트만 돌린다. 판정 체계와 양식은 같다.
- PR·diff 리뷰는 바뀐 파일의 영역만 읽는다. 게이트는 2단계대로 한 번 돌린다(멈춤 판정에 merge 단계 전부가 필요하다). 범위의 base는 직전 리뷰(diff 리뷰 포함)가 본 범위의 끝 커밋, head는 맡긴 쪽이 정한 커밋(없으면 fetch한 `origin/main`)이고 둘을 머리말에 적는다. 판정 체계·양식·ID 체계(`NN-MM`)는 같고, 수정 라운드의 diff 리뷰는 그 라운드 README 「조치」 절 아래 절로 적는다.
- 리뷰 중에 코드를 고치지 않는다. 의심 결함은 별도 worktree의 임시 테스트로 확인하고 그 코드는 리뷰 문서나 공유 노트에만 남긴다. 리뷰 문서는 리뷰 시점 기록이다. 고친 뒤에도 영역 문서를 고치지 않고, 처리 결과는 같은 README의 「조치」 절에 적는다.
### 4.2 결함 수정
@@ -86,11 +86,11 @@
1. 그 라운드의 새 High 0.
2. 그 라운드의 새 P1 0.
3. merge 단계 게이트 전부 통과([reference/gates.md](reference/gates.md) 3절 방법).
3. merge 단계 게이트 전부 통과([reference/gates.md](reference/gates.md) 3절 방법). FE-GATE-013을 어떻게 셀지는 결정 대기라, 그동안은 같은 절의 문구로 보고하고 멈출지는 소유자가 정한다.
- 채워도 바로 끝내지 않는다. 그 라운드의 Medium·Low를 고치고 멈춘다. 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 남긴다(형식 [reference/decisions.md](reference/decisions.md) 3절). 이유 없는 이월("나중에", "범위 밖")은 남기지 않는다.
- 마지막 Medium·Low 수정은 다음 리뷰를 받지 않는다. 그래서 그 수정도 4.2절 6단계와 merge 판정을 그대로 거친다. 짝 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 두 기준을 맞추지 않는다(소유자 결정 2026-11-05 「각자 유지」).
- 2026-11-03 리뷰의 수정 라운드 뒤로 세 라운드를 더 돌아도 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게 보고한다.
- 2026-11-03 리뷰의 수정 라운드 뒤로 세 라운드를 더 돌아도 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게 보고한다. 라운드는 전체 리뷰 한 번이다(diff 리뷰는 세지 않는다). 2026-11-05·06 리뷰가 그 첫째·둘째다.
- 수정 결과의 "고침"은 확정이 아니다. 다음 리뷰가 ID별로 다시 판정한다. 보고에도 "다음 리뷰에서 재판정"이라고 적는다.
## 5. 완료 기준
@@ -99,7 +99,7 @@
- 결함 수정(모든 발견에 공통):
1. 동작을 바꾸면 RED → GREEN이 실행으로 있다. 없으면 "RED 없음 — 이유"와 대신한 증거가 있다.
2. 검출력이 문제였던 발견은 변이를 다시 넣어 새 테스트가 실패한다.
3. 커밋 전 게이트 8개가 통과한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`.
3. 커밋 전 검사 8개(package script)가 통과한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`.
4. 묶음 끝과 통합 때는 더해서 `check:ci`, `check:adapter-inventory`, `verify:documentation`, `test:sample-removal`, `build`가 통과한다.
5. adapter 파일을 더하거나 옮겼으면 INVENTORY를 같은 커밋에서 고쳤다.
6. 공용 로직은 kernel이나 `src/contracts/`에 있고 새 파일 단위 예외가 없다.
@@ -107,7 +107,7 @@
8. 논리 변경 하나에 커밋 하나, 메시지에 발견 ID, 바꾼 파일만 stage했다.
9. 문서 요구는 문서의 각 주장이 코드 위치를 가리키는 것으로 확인했다.
- 발견별 상태가 「고침 / 일부 / 결정 대기」 중 하나이고, 리뷰 가이드 35.6절의 다섯 연결(원래 위험, 바꾼 코드, 그 위험을 잡는 검증, 검증한 버전·환경·결과, 남은 제한)이 있다.
- 리팩터링: 테스트 변경 없이 커밋 전 게이트 8개가 통과한다. 줄어든 이해 비용을 한 문장으로 말할 수 있다.
- 리팩터링: 테스트 변경 없이 커밋 전 검사 8개가 통과한다. 줄어든 이해 비용을 한 문장으로 말할 수 있다.
- 성능: `check:bundle`(FE-GATE-012)과 `test:performance`(FE-GATE-026)가 통과하고, 전후 차이가 측정 잡음보다 크다(잡음 크기를 함께 적는다).
- 구조 변경: `check:architecture`, `check:adapter-inventory`, `verify:documentation`, FE-GATE-020이 통과한다. merge 가능을 말하려면 merge 단계 전부가 통과했다.
- 테스트 구조: 변이나 결정적 재현이 고친 뒤 기대대로 실패·통과하고, 반복 실행 실패 0과 횟수가 있다.
+10 -9
View File
@@ -17,30 +17,30 @@
## 3. 크기와 사고 순서
- 생성 명령 출력 그대로 기능 하나를 채우면 중간이다(기능 폴더 하나 안).
- 큼: 새 context를 여는 일, 기능 폴더 밖 파일(`docs/manual/03-outside-feature-folder.md`)을 생성 명령 밖에서 고치는 일, 짝 백엔드와 새 계약(오류 code, 응답 모양)을 맞추는 일, 초기 JS 예산을 올려야 하는 일. 큰 일은 [research-design.md](research-design.md)로 소유자 검토를 먼저 받는다.
- 생성 명령 출력 그대로 기능 하나를 채우면 중간이다(기능 폴더 하나 안). 생성 명령이 함께 만드는 새 context(`--context` 없이 생기는 `<base>-context`)도 중간이다. 템플릿에는 context가 없어 첫 기능은 늘 이렇게 시작한다.
- 큼: context를 손으로 만들거나 기존 context 경계를 바꾸는 일, 기능 폴더 밖 파일(`docs/manual/03-outside-feature-folder.md`)을 생성 명령 밖에서 고치는 일, 짝 백엔드와 새 계약(오류 code, 응답 모양)을 맞추는 일, 초기 JS 예산을 올려야 하는 일. 큰 일은 [research-design.md](research-design.md)로 소유자 검토를 먼저 받는다.
- 선행 사례: `docs/manual/reference/patterns.md`(기능 개발 패턴과 예제 위치), 매뉴얼 안의 코드 조각. 템플릿에는 복사해 볼 기능 샘플이 없다. 다른 기능 폴더를 복사해 이름을 바꾸지 않는다.
- 스킬: `new-feature`(이 절차의 실행 순서표). 매뉴얼 01장이 단계마다 「쓸 스킬」을 적는다. 동작은 `superpowers:test-driven-development`로 테스트를 먼저 쓴다.
## 4. 절차
1. `docs/manual/README.md`와 `docs/manual/01-add-a-feature.md` 0단계(경계와 소속)를 읽고 크기를 정한다.
2. 뼈대: `corepack pnpm create:feature <id>`(필요하면 `--context`, `--with-create`, `--keyed`). 생성은 파일을 쓰는 일이라 노트북에서 해도 되지만 node가 필요하다. 소유자 환경에서는 desktop에서 만들고 결과를 커밋으로 가져오거나, 노트북 깨끗한 복제본에서 만든다([operate.md](operate.md) 4.1절).
2. 뼈대: `corepack pnpm create:feature <id>`(필요하면 `--context`, `--with-create`, `--keyed`). 소유자 환경에서는 pnpm을 노트북에서 돌리지 않으니 desktop에서 만들고 만든 파일을 돌려받는다: `scripts/verify.sh script create:feature --apply-back -- <id> --with-create`. 노트북 작업 트리에 생긴 파일을 `git status`로 본다([operate.md](operate.md) 4.1절).
3. 출력의 `Next:` 목록을 보고에 옮긴다. 그 목록이 돌릴 명령과 다시 쓸 기록(초기 JS 기록 등)이다.
4. 매뉴얼 01장 2~10단계로 뼈대를 실제 기능으로 바꾼다. 막히면 02장 결정표(context 경계, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿, 파일 업로드), 폴더 밖 파일은 03장, 짝 백엔드 인증은 04장.
5. import는 기능 폴더 안 계층 규칙과 꼭 지킬 것 1~3을 지킨다. 편집 훅의 경계 알림(N3)이 나오면 그 자리에서 고친다. 다른 기능을 import하지 않는다. adapter는 기능의 `adapters/`나 배럴로만 닿는다.
6. 테스트는 `tests/features/<id>/`에 둔다(기능과 함께 지워진다). 결과 불명 쓰기와 재전송 입구는 `docs/manual/02-decision-tables.md` 3·4절 기준으로 테스트한다.
7. 기준선과 증거: 초기 JS 기록은 생성 출력 `Next:`의 명령으로 다시 쓰고 같은 커밋에 넣는다. 손으로 고치지 않는다. 예산(`config/performance/budgets.json`)을 넘으면 올리기 전에 멈추고 묻는다(꼭 지킬 것 4).
8. 제거 확인: 매뉴얼 01장 11단계. 기능을 지운 사본이 게이트를 통과해야 한다(`test:sample-removal -- --feature=<id>`, FE-GATE-020).
9. desktop에서 merge 단계를 돌린다: `scripts/verify.sh merge`. 결과를 보고 싶으면 서브에이전트 `arch-reviewer`(경계 리뷰)와 `verify-app`(desktop에서 앱을 띄워 그 라우트를 연다)에 맡긴다.
7. 기준선과 증거: 초기 JS 기록(`config/scale/feature-shape-ceilings.json`의 `initialJavascript`)은 생성 출력 `Next:`의 명령으로 다시 쓰고 같은 커밋에 넣는다. 손으로 고치지 않는다. desktop에서 돌려 돌려받는다: `scripts/verify.sh exec --apply-back -- node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`. 예산(`config/performance/budgets.json`)을 넘으면 올리기 전에 멈추고 묻는다(꼭 지킬 것 4).
8. 제거 확인: 매뉴얼 01장 11단계. 기능을 지운 사본이 게이트를 통과해야 한다: `scripts/verify.sh script test:sample-removal -- --feature=<id>`. merge 단계의 FE-GATE-020은 목록에 적은 기능과 새로 생성한 기능만 지우므로 이 기능의 제거를 대신 보여 주지 않는다.
9. desktop에서 merge 단계와 lab 게이트를 돌린다: `scripts/verify.sh merge`, `scripts/verify.sh gate FE-GATE-026`(새 기능은 lazy 라우트를 더하므로 늘 돌린다). 결과를 보고 싶으면 서브에이전트 `arch-reviewer`(경계 리뷰)와 `verify-app`(desktop에서 앱을 띄워 그 라우트를 연다)에 맡긴다.
## 5. 완료 기준
- 생성 명령으로 시작했고, 템플릿 소유 파일을 생성 명령 밖에서 고치지 않았다(고쳤으면 큼으로 올려 결정을 받았다).
- 동작마다 테스트가 있고 RED → GREEN을 봤다.
- 초기 JS 기록과 기능 모양 기록이 빌드와 맞는다(`test:unit` 안의 대조).
- `scripts/verify.sh merge`가 통과했다(FE-GATE-013은 [operate.md](operate.md) 4.1절대로 적었다). 라우트 로딩을 바꿨으면 `test:performance`(FE-GATE-026)도 돌렸다.
- 기능을 지운 사본이 통과한다(FE-GATE-020 안의 드릴).
- 초기 JS 기록이 빌드와 맞는다(`test:unit` 안의 대조).
- `scripts/verify.sh merge`가 통과했고(FE-GATE-013은 [reference/gates.md](reference/gates.md) 3절 문구로 적었다) FE-GATE-026도 통과했다.
- 이 기능을 지운 사본이 통과한다(`test:sample-removal -- --feature=<id>`).
- 다운스트림에 보이는 변경(공개 포트, 생성 명령 출력)이 있으면 `CHANGELOG.md` 미출시 절에 적었다.
## 6. 하지 말 것
@@ -56,6 +56,7 @@
- 생성 명령이 거부하면 `docs/manual/reference/errors.md`에서 메시지를 찾는다. 고칠 파일이 적혀 있다.
- 짝 백엔드 응답 모양·오류 code가 문서와 다르면 코드(백엔드 생성기, 이 repo의 `src/adapters/http/backend-envelope.ts`)까지 따라가 사실을 적고 묻는다. 문서만 보고 판정 표를 정하지 않는다.
- 기능 폴더 밖을 고쳐야만 되면 거기서 멈추고 [README](README.md) 5절 형식으로 묻는다.
- brief가 매뉴얼 예시 이름(`invoice-feature` 등)을 기능 ID로 주면 그대로 만들지 말고 묻는다. 템플릿 시험(`tests/unit/manual-code-blocks.test.ts`)이 저장소 사본에 그 이름으로 기능을 만든다.
## 8. 보고 형식
+2
View File
@@ -37,6 +37,8 @@
- **CI env.** `scripts/verify.sh`는 게이트를 workflow와 같은 꼴의 env로 돌린다: `CI=true`, `VITE_COMMIT_SHA`(그 worktree의 HEAD), `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE`(`@sha256:` digest 꼴). `CI=true`를 빼면 CI에서만 나는 실패를 놓친다([reference/gates.md](reference/gates.md) 4절).
- **desktop의 FE-GATE-013.** ssh 셸에서 비특권 user namespace가 막혀 `test:system`의 provider 테스트가 호스트 원인으로 실패한다. 시스템 설정은 바꾸지 않는다. `scripts/verify.sh parts FE-GATE-013`으로 그 게이트의 명령을 하나씩 끝까지 돌려, 실패가 호스트 전제 하나뿐인지와 뒤 명령의 결과를 함께 적는다. 이 게이트를 멈춤 기준에서 어떻게 셀지는 결정 대기다([reference/decisions.md](reference/decisions.md)).
- **노트북에서 꼭 돌려야 하면** 노트북 checkout이 아니라 깨끗한 복제본(`git clone --no-hardlinks`, 그 뒤 `corepack pnpm install --frozen-lockfile --offline`)에서 돌리고 vite가 들어가는 게이트에 `CHOKIDAR_USEPOLLING=1`을 준다. 노트북 checkout의 `.claude/worktrees/`가 `test:system`의 repo 복사와 vite 파일 감시를 깨뜨린다.
- **desktop에서 파일을 만드는 명령**(생성 명령, 기준선 다시 쓰기)은 `--apply-back`으로 결과를 노트북 작업 트리에 받는다: `scripts/verify.sh script create:feature --apply-back -- <id>`, `scripts/verify.sh exec --apply-back -- <명령…>`. 바뀐 파일은 언제나 로그 폴더의 `changes.patch`에도 남는다.
- **한 테스트 파일**도 desktop에서: `scripts/verify.sh exec -- node scripts/run-vitest.ts run <파일>`.
- desktop의 비대화형 ssh에는 node가 PATH에 없다. 스크립트가 `~/.nvm/versions/node/v<.nvmrc>/bin`을 앞에 붙인다. 손으로 돌릴 때도 같다.
### 4.2 게이트 실행과 기록
+2 -2
View File
@@ -26,7 +26,7 @@
| O-1 | 2026-09-16 | 이 repo는 템플릿이다. 소비자 없는 코드와 빈 레지스트리는 확장 지점이지 죽은 코드가 아니다 | 옛 루트 `CLAUDE.md` 리뷰 전제 | `AGENTS.md` 첫 문단, `structure.md` 2절 |
| O-2 | 2026-09-16 | adapter 배럴을 공개 경계로 만든다(배럴 폐지안 기각) | 옛 `CLAUDE.md`, `docs/architecture/layers.md` | 꼭 지킬 것 1 |
| O-3 | 2026-09-16 | 갈라진 IndexedDB 복사본은 kernel(`src/adapters/platform/`)로 모은다. 새 파일 단위 예외를 만들지 않는다 | 옛 `CLAUDE.md`, `SPEC.md` 공통 완료 기준 6 | 꼭 지킬 것 2 |
| O-4 | 2026-11-01 | 커밋·PR은 design-docs `conventions/commit-and-pr.md`를 따른다. AI 꼬리말은 어디에도 넣지 않는다 | repo 밖 | `README.md` 4절 |
| O-4 | 2026-11-01 | 커밋·PR은 design-docs `conventions/commit-and-pr.md`를 따른다. AI 꼬리말은 어디에도 넣지 않는다 | repo 밖 | `docs/work/README.md` 4절 |
| O-5 | 2026-11-03 | merge 가능 판정은 `ci:gate`로 merge 단계 전부를 workflow env로 돌려서 한다. 고른 스크립트 목록으로 판정하지 않는다 | repo 밖. 실행 기록은 1103 README 14.5절 | `gates.md` 3절 |
| O-6 | 2026-11-03~05 | 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 이유와 함께 남긴다 | repo 밖 | `improve.md` 4.5절 |
| O-7 | 2026-11-03~05 | 리뷰·수정에 스킬을 쓴다 | repo 밖 | `improve.md` 3절 |
@@ -88,4 +88,4 @@
## 4. 커밋·PR
정본은 repo 밖 design-docs `conventions/commit-and-pr.md`다. 이 repo에서 덧붙이는 것은 [review-criteria.md](review-criteria.md) 10절(발견 ID 꼬리말, CHANGELOG 리뷰 ID, BREAKING)과 [../README.md](../README.md) 4절이다. PR 본문은 그 문서 5.3절의 칸을 쓰고 「위험과 영향」과 「검증」은 비우지 않는다. 병합은 소유자가 한다.
정본은 repo 밖 design-docs `conventions/commit-and-pr.md`다. 이 repo에서 덧붙이는 것은 [review-criteria.md](review-criteria.md) 11절(발견 ID 꼬리말, CHANGELOG 리뷰 ID, BREAKING)과 [../README.md](../README.md) 4절이다. PR 본문은 그 문서 5.3절의 칸을 쓰고 「위험과 영향」과 「검증」은 비우지 않는다. 병합은 소유자가 한다.
+7 -4
View File
@@ -1,10 +1,10 @@
# 게이트
무엇을 돌릴지는 **언제인지**로 정한다. 작업 중에는 바뀐 테스트 파일만, 커밋 전에는 빠른 게이트 8개, 통합 때는 5개를 더, merge 가능을 말할 때는 merge 단계 전부를 CI와 같은 env로 돌린다. 어디서 어떻게 돌리는지는 [../operate.md](../operate.md) 4.1절이다.
무엇을 돌릴지는 **언제인지**로 정한다. 작업 중에는 바뀐 테스트 파일만, 커밋 전에는 검사 8개(package script), 통합 때는 5개를 더, merge 가능을 말할 때는 merge 단계 전부를 CI와 같은 env로 돌린다. 어디서 어떻게 돌리는지는 [../operate.md](../operate.md) 4.1절이다.
```text
작업 중 바뀐 테스트 파일 하나 (2절)
커밋 전 빠른 게이트 8개 (2절)
커밋 전 검사 8개(package script) (2절)
묶음 끝·통합 + 5개 (2절)
merge 판정 scripts/verify.sh merge (stage 전부, CI env) (3절)
리뷰 시작 merge 단계 + documentation 단계 (3절)
@@ -24,12 +24,15 @@ scripts/verify.sh <단계> [대상…] [--on here|<호스트>] [--log <이름>]
| `hooks` | repo 훅·검사기·장부 시험(`python3 -m unittest discover -s scripts/tests`) | 여기 |
| `gate <ID>…` | 게이트마다 `corepack pnpm ci:gate <ID>`, CI env로 | desktop |
| `parts <ID>` | 그 게이트의 명령(`commandIds`)을 하나씩 끝까지. 음성 fixture(`expect: fail`)는 정해진 종료 코드면 통과 | desktop |
| `script <이름>…` | package script를 하나씩(예: `verify:documentation`, `test:unit`) | desktop |
| `script <이름>… [-- 인자…]` | package script를 하나씩(예: `verify:documentation`). `--` 뒤 인자는 script가 하나일 때만 넘긴다(예: `scripts/verify.sh script test:sample-removal -- --feature=<id>`) | desktop |
| `exec -- <명령…>` | 명령 하나. 한 테스트 파일(`node scripts/run-vitest.ts run <파일>`)이나 package script가 아닌 node 스크립트 | desktop |
| stage id | `config/ci/gates.json` `stages`의 그 단계 `gateIds` 전부 | desktop |
- stage id는 계약 파일에서 읽는다. 단계가 바뀌면 스크립트를 고치지 않아도 따라간다. `--dry-run`은 돌릴 명령만 보인다.
- 게이트·stage는 실패가 있어도 끝까지 돌고 게이트마다 `<이름> rc=<n> <초>s` 한 줄을 남긴다. 하나라도 실패하면 rc=1이다. 종료 코드 2는 사용법, 4는 원격 준비 실패다.
- 잘못된 단계·게이트 ID는 desktop에 보내기 전에 노트북에서 거절한다.
- desktop에서 바뀐 파일(생성 명령, 기준선 다시 쓰기의 결과)은 로그 폴더의 `changes.patch`에 남는다. `--apply-back`을 주면 그 패치를 노트북 작업 트리에 얹는다. 예: `scripts/verify.sh script create:feature --apply-back -- <id> --with-create`.
- `VERIFY_SNAPSHOT=1`을 주면 `artifacts`·`dist`·`test-results`를 로그 폴더의 `snapshot/`에 복사한다. 리뷰어가 함께 읽는 사본이다.
- 환경 변수로 바꿀 수 있는 것(호스트, 원격 checkout, 기준 ref, 잠금, 로그 폴더, node 경로)은 스크립트 머리 주석에 있다. 복사한 프로젝트는 [../operate.md](../operate.md) 4.1절과 이 값만 자기 환경으로 바꾼다.
## 2. 언제 무엇을
@@ -65,7 +68,7 @@ release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회
**가끔 떨어지는 게이트.** 다시 돌려 통과시킨 결과를 "통과"로 쓰지 않는다. 실패한 회차를 그대로 적고 원인을 찾는다([testing.md](testing.md) 5절). "세 번째 실행에서 통과"로 적혔던 FE-GATE-008의 두 실패는 둘 다 테스트 결함이었다. 원인을 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0을 적는다.
**desktop에서 FE-GATE-013.** ssh 셸에서 비특권 user namespace가 막혀 `bwrap --unshare-net`이 실패하고, `test:system`의 provider 테스트가 호스트 원인으로 떨어진다. 사전 점검(`scripts/check-system-test-prerequisites.ts`)은 이제 이 제한을 이름으로 대며 실패한다. 이 게이트를 멈춤 기준에서 어떻게 셀지는 결정 대기다([decisions.md](decisions.md)). 결정 전까지 merge 판정 보고에는 FE-GATE-013을 "호스트 제약 실패"로 적고, `scripts/verify.sh parts FE-GATE-013`으로 뒤 명령의 결과를 함께 적는다. 시스템 설정은 바꾸지 않는다.
**desktop에서 FE-GATE-013.** ssh 셸에서 비특권 user namespace가 막혀 `bwrap --unshare-net`이 실패하고, `test:system`의 provider 테스트가 호스트 원인으로 떨어진다. 사전 점검(`scripts/check-system-test-prerequisites.ts`)은 이제 이 제한을 이름으로 대며 실패한다. 이 게이트를 멈춤 기준에서 어떻게 셀지는 결정 대기다([decisions.md](decisions.md)). 결정 전까지 merge 판정 보고는 이 문구로 쓴다: 「merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약 실패(뒤 명령 결과 첨부). merge 가능 여부는 소유자가 정한다(FE-GATE-013을 멈춤 기준에서 어떻게 셀지의 결정 대기, [decisions.md](decisions.md) 3.1절)」. 뒤 명령 결과는 `scripts/verify.sh parts FE-GATE-013`으로 낸다. 시스템 설정은 바꾸지 않는다.
## 4. CI env에서만 나는 실패
+23 -5
View File
@@ -1,6 +1,6 @@
# 리뷰 기준
이 repo를 리뷰할 때(전체·모듈·PR·diff 리뷰 모두)의 기준이다. 일반 기준의 정본은 리뷰 가이드다: design-docs `conventions/template-maturity-review-guide.md`(이 문서의 「가이드 N절」). repo 안 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`는 정본 위치만 적은 포인터다(절 번호는 정본과 같다). 가이드를 읽을 수 없는 프로젝트도 이 문서만으로 판정할 수 있게 썼다. 절차는 [../improve.md](../improve.md) 4.1절이다.
이 repo를 리뷰할 때(전체·모듈·PR·diff 리뷰 모두)의 기준이다. 일반 기준의 정본은 리뷰 가이드다: design-docs `conventions/template-maturity-review-guide.md`(이 문서의 「가이드 N절」). repo 안 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`는 정본 위치만 적은 포인터다(절 번호는 정본과 같다). 가이드를 읽을 수 없는 프로젝트를 위해 발견 양식과 등급 정의를 7·8절에 줄여 옮겼다. 절차는 [../improve.md](../improve.md) 4.1절이다.
```text
발견 하나 = 항목 하나 (관련 관점 번호를 모두 붙인다, 가이드 0.3절)
@@ -121,7 +121,20 @@
## 7. 리뷰 문서 형식
**폴더와 ID.** 폴더는 `docs/reviews/<YYYY-MM-DD>-maturity-review/`, README 하나와 영역 문서 `NN-<영역>.md`. 발견 ID는 라운드 안에서 `NN-MM`(영역 번호-순번), 라운드 밖에서는 `MMDD/NN-MM`(가이드 36.3절). 총괄이 직접 찾은 발견은 관련 영역 번호를 쓰고 README 「오케스트레이터 발견」 절에 둔다.
**폴더와 ID.** 폴더는 `docs/reviews/<YYYY-MM-DD>-maturity-review/`, README 하나와 영역 문서 `NN-<영역>.md`. 발견 ID는 라운드 안에서 `NN-MM`(영역 번호-순번), 라운드 밖에서는 `MMDD/NN-MM`(가이드 36.3절). 총괄이 직접 찾은 발견은 관련 영역 번호를 쓰고 README 「오케스트레이터 발견」 절에 둔다. diff 리뷰도 같은 체계를 쓴다(바뀐 파일의 영역 번호).
**발견 하나의 칸**(가이드 36.3절을 줄인 것). 설계 선택이 없는 단순 결함은 「결정의 근거」「대안 비교」「단순화의 보존 조건」「재검토 조건」을 `적용 제외 — 이유 한 문장`으로 둔다.
| 칸 | 적을 것 |
| --- | --- |
| ID·제목 | `NN-MM`과 구체적인 문제 |
| 성격, 관련 관점 | 2절의 넷 중 하나, 28개 관점 번호 전부 |
| 근거, 발생 조건, 영향 | 파일·심볼·설정·실행 결과(`file:line`), 어떤 입력·순서·장애·규모에서, 누구에게 무엇이 |
| 심각도·우선순위, 통제, 증거 | 등급과 이유(3절), M0~M4 또는 `미확인`, E0~E4(8절) |
| 확실성과 남은 가정, 결정의 근거 | 확인한 사실과 추론의 경계, 설계 선택이면 지금 제약과 선택 이유 |
| 최소 개선 방향, 대안 비교, 비용·부작용 | 위험을 줄이는 가장 작은 변경, 여러 선택지면 비교 |
| 완료 기준, 검증 방법 | 끝났는지 볼 관찰 가능한 조건, 그 위험을 직접 다루는 테스트·실험 |
| 상태, 재검증 결과 | 열림·고침·일부·결정 대기, 변경 버전과 결과 |
**README 절 순서.** 가이드 36.5절 요약 일곱 항목과 36.1·36.2절을 담는다.
@@ -144,17 +157,22 @@
**영역 문서 절 순서.** 0 결론(몇 줄) · 1 범위(36.1절, 읽은 경로, 돌린 것, 확인하지 못한 것) · 2 지난 발견 재판정(6절) · 3 이번 발견(36.3절 양식. 설계 선택이 없는 단순 결함은 선택 비교 칸을 「적용 제외」와 한 문장 이유로) · 4 28개 관점 판정(36.2절) · 5 설계 선택 설명(가이드 41절, 여러 타당한 선택지가 있는 발견만) · 6 실험·실행 기록.
## 8. 판단을 적는 법
## 8. 통제와 증거의 뜻
- 통제(가이드 35.4절, 선정한 규칙 하나에 매긴다): M0 지킬 수단이 없음을 확인함 · M1 규칙이 적혀 있음 · M2 필요한 코드 경로에 구현됨 · M3 자동 검사가 위반을 잡음 · M4 타입·공개 범위·권한 같은 경계가 위반을 막음. 읽지 못했으면 M0가 아니라 `미확인`이다.
- 증거(가이드 35.5절): E0 문서·주장 · E1 코드·설정을 읽어 확인 · E2 명시한 테스트가 그 버전에서 통과 · E3 실제 의존성·부하·장애 조건의 통합·실험 · E4 실제 운영 관찰. 높은 번호 하나가 낮은 번호의 다른 검증을 대신하지 않는다.
## 9. 판단을 적는 법
- 확인한 사실 / 기록된 의도 / 추론을 나눈다(가이드 41.3절). 다운스트림 파일을 열지 않고 이름으로 추정한 문장이 CHANGELOG에 틀린 이행 안내로 남은 일이 있다.
- 결정이 필요한 것은 선택지, 권하는 안, 결정할 사람을 적는다([decisions.md](decisions.md) 3절 형식).
- 리뷰에 쓴 스킬과 그 스킬의 기준으로 무엇을 봤는지를 「범위」 절에 한 줄씩 적는다 **[제안]**.
## 9. 총괄이 README에 쓰는 것
## 10. 총괄이 README에 쓰는 것
범위(가이드 36.1절), 28개 관점 판정표(36.2절), 최종 요약(36.5절), 발견 색인. High 이상 발견은 코드에서 직접 다시 확인한 뒤에 쓴다.
## 10. 커밋·CHANGELOG의 리뷰 ID
## 11. 커밋·CHANGELOG의 리뷰 ID
- 결함 수정 커밋은 꼬리말 `Refs:`에 라운드 접두어를 붙인 발견 ID를 적는다(`Refs: <MMDD>/<NN>-<MM>` 꼴). 형식의 정본은 design-docs `conventions/commit-and-pr.md` 3.4절과 가이드 36.3절이다.
- `CHANGELOG.md`의 리뷰 ID도 `MMDD/NN-MM` 꼴이어야 한다. `tests/unit/changelog-review-ids.test.ts`가 검사한다.