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
+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`가 검사한다.