문제: 작업 매뉴얼·루트 지침·스킬이 「desktop의 FE-GATE-013은 호스트 제약
실패로 적고 merge 가능 여부는 소유자가 정한다(결정 대기 D8)」라고 적고
있다. 1d3eb901 뒤로 workflow와 scripts/verify.sh는 이 게이트를
scripts/run-in-system-container.sh 안에서 돌리고, 다른 게이트처럼 rc로
센다. CHANGELOG에는 이 브랜치의 변경이 없다.
고른 방법:
- gates.md 3절 문단을 「시스템 컨테이너 안에서 돈다」로 바꾸고, AGENTS.md
·improve.md·new-feature.md·operate.md·desktop-gates 스킬의 기록법
문구를 그 절을 가리키게 고친다.
- decisions.md: 소유자 결정(2026-11-11, design-docs template-program
README 5절 e)을 2.1절 행으로 더하고 열린 결정 대기 D8을 닫는다.
evidence.md의 근거 행을 새 규칙 이름과 runner 사건으로 고친다.
- docs/operations/ci-quality-gates.md, docs/testing/taxonomy.md,
README.md에 컨테이너 경로와 그 한계(root라 비특권 userns 조건은 증명하지
않음, privileged를 막는 runner에서는 깨짐)를 적는다.
- CHANGELOG 미출시 절에 이 브랜치의 변경을 적는다.
위험·한계: desktop·runner에서 FE-GATE-013이 실제로 초록인지는 이 브랜치
끝의 merge 단계 실행으로 확인한다.
검증: 노트북 scripts/verify.sh docs rc=0. desktop verify:documentation
PASS_SCOPED, 문서를 읽는 시험 넷(changelog-review-ids,
documentation-readiness, template-contract-documents,
deletable-history-documents) 29개 통과.
10 KiB
근거와 이력
이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 ID를 모은다. 진입 문서(루트 AGENTS.md·CLAUDE.md, docs/work/의 README·playbook·reference, .claude/ 아래 문서)는 ID 없이 내용과 날짜로 쓰고, ID는 여기에 둔다(scripts/check-work-docs.py가 본다).
표기. 리뷰 ID는 리뷰 가이드 36.3절의 라운드 밖 표기 MMDD/NN-MM이다. 1103/11-07은 docs/reviews/2026-11-03-maturity-review/의 발견 11-07이다. 「1105 README」는 docs/reviews/2026-11-05-maturity-review/README.md다. 라운드: 0925·0929·1101·1103·1105(네 번째)·1106(다섯 번째). 0924는 docs/reviews/2026-09-24-src-full-review.md다.
1. 이 매뉴얼이 나온 곳
- 개선 작업 매뉴얼 초안(docs/improvement 폴더 11개 파일, 2026-11-05, 브랜치 docs/improvement-manual, PR #6. main에 없다)을 백엔드
docs/work/와 같은 모양으로 옮겼다(2026-11-08). 초안은 main에 들어가지 않았고, 이 폴더가 그것을 대신한다. - 하네스 설계: design-docs
harness/01-harness-design.md(2026-11-07, 13절 소유자 결정). 루트 지침·훅·스킬·서브에이전트·검증 진입점·장부의 근거다. - 옛 루트
CLAUDE.md(리뷰 기준과 전체 리뷰 절차 26줄)의 내용은 reference/review-criteria.md 1절과 improve.md 4.1절로 옮겼다. 옛 3단계의 "영역별로 서브에이전트를 병렬로"는 소유자 결정 2026-11-07에 맞춰 「결과만 받는 리뷰는 서브에이전트, 문서를 커밋하는 리뷰·파일을 바꾸는 위임은 하위 세션」으로 고쳤다. 옛 2단계의 손으로 적은 게이트 목록은 merge 단계 전부로 바꿨다(1105/12-03). SPEC.md「공통 완료 기준」 9개를 improve.md 5절로 옮겼다. 문서 체계 정리가SPEC.md를 이력으로 옮길 수 있게 하려는 것이다(프론트 정리 프로그램의 총괄 결정, 2026-11-07).
1.1 초안 장 → 이 폴더
| 초안 | 옮긴 곳 | 바꾼 것 |
|---|---|---|
README.md(정본 표, 읽는 순서, 결정 M-1~M-10) |
README.md, 결정은 reference/decisions.md | M-1(위치 docs/improvement)은 docs/work/로 대체. M-3(§1 링크로 검사 범위에 넣음), M-4(지워도 되는 목록에 넣지 않음), M-8(repo 밖 문서는 코드 표기)은 그대로 규칙이 됐다. M-10(AGENTS.md는 추적하지 않는 사본)은 소유자 결정 2026-11-07로 뒤집혔다: AGENTS.md가 정본이다 |
01-procedures.md |
improve.md 3·4절 | 스킬 표, 여섯 작업 종류의 단계와 완료 기준 |
02-review-criteria.md |
reference/review-criteria.md | 28개 관점 표의 대표 발견 열은 이 문서 3절로 |
03-folder-module-structure.md, 04-code-structure.md |
reference/structure.md | 한 문서로 합침 |
05-test-structure.md |
reference/testing.md | |
06-performance.md |
reference/performance.md | 1106 D9(예산 206,848 B)를 더함 |
07-verification-gates.md |
reference/gates.md, operate.md 4.1·4.2절 | 7절 소유자 환경의 손 절차는 scripts/verify.sh로 바뀌었다. desktop runner(/tmp/claude-gates/run-merge-stage.sh)는 스크립트가 대신한다 |
08-decisions-records.md |
reference/decisions.md | 열린 결정 대기를 1106 기준으로 갱신(D8·D11 더함, D4·D5는 1106 README 7절에 없음) |
09-working-method.md |
delegate.md, 멈춤 기준은 improve.md 4.5절 | 「총괄이 자주 한 실수」는 delegate·improve 「자주 하는 실수」로 |
appendix-defect-patterns.md |
reference/defect-patterns.md | 번호를 다시 매김(4절). 1106 대표 발견을 더함 |
2. 규칙과 사건
| 규칙(이 매뉴얼) | 사건 | 출처 |
|---|---|---|
merge 판정은 stage 전부를 CI env로(gates.md 3절) |
고른 스크립트 23개 통과라고 보고했지만 merge 게이트 셋이 실패. CI=true 없이 14개 통과 뒤 넣자 005·008·020 실패 |
1103 README 10.5·14.5절, 1103/11-08, 1105/12-03 |
리뷰 중 실행은 한 번(delegate.md 4.2절) |
영역 리뷰어 16개가 각자 desktop에서 실행해 잠금 줄 30여 건, 32건 취소 | 1105 README 11.4·11.5절 |
다시 돌려 통과한 것은 통과가 아니다(gates.md 3절) |
FE-GATE-008 "세 번째 실행에서 통과"의 두 실패가 모두 테스트 결함 | 1103/11-09, 1103/11-10, 1103 README 14.5절 12~14회차 |
부하 탓으로 닫지 않는다(testing.md 5절) |
부하 탓으로 적었던 두 실패가 모두 테스트 결함 | 1103 README 14.7절 정정 두 줄 |
"고침"을 믿지 않는다(improve.md 4.5절) |
1103 조치의 "고침" 13건이 다음 라운드에서 "일부"로 정정 | 1105 README 3.1절 |
수정이 새로 가정하는 것(structure.md 11절) |
1105 새 발견 48건 중 22건이 지난 수정에서 나옴. 1106 diff 리뷰의 Medium 2건도 그 라운드 수정이 만든 회귀 | 1105 README 4절 끝, 1105 README 6절 원인 5, 1106 README 16.7절 |
템플릿 원래 상태 밖에서도(improve.md 4.2절 6단계) |
기능 추가·확장 지점 채움·객체 셋 이상에서 다시 결함 | 1105 README 6절 원인 1, 1103/12-01, 1105/09-01, 1105/14-01, 1103/05-01, 1105/16-04 |
release 단계 게이트도 돌린다(gates.md 2절) |
lab 게이트 회귀가 147커밋 동안 아무 게이트에도 안 걸림 | 1103/15-01, 1103 README 5절 원인 2 |
짝 사실은 코드까지(structure.md 8절) |
판정 표를 백엔드 계약 문서만으로 정해 High | 1103/03-01, 1103 README 10.5절 |
지울 때 지키던 것을 찾는다(structure.md 9절) |
V2 삭제 때 지운 검사·테스트가 지키던 동작을 놓침 | 1103/07-01, 1103/10-04 |
지워도 되는 문서를 코드가 읽지 않는다(structure.md 4절) |
테스트가 리뷰 문서를 열어 제거 드릴 셋을 깨뜨림 | tests/unit/deletable-history-documents.test.ts 머리말 |
드릴 복사 목록은 하나(structure.md 12절) |
복사 목록에 README.md·CHANGELOG.md가 없어 드릴 넷 중 셋이 항상 실패 |
1103/02-06 |
경로를 백틱 밖으로 옮기지 않는다(docs-writing.md 4절) |
참조 기능 경로 26줄을 백틱 밖으로 옮긴 것이 검사 약화로 기록 | 1105/14-03 |
npm run 금지(gates.md 2절) |
제거 드릴을 npm run으로 돌려 모든 검사가 Unknown command |
1103 README 10.4절 |
임시 worktree의 pnpm verify:documentation(delegate.md 9절) |
pnpm이 재설치를 시도하다 TTY 없음으로 멈춰 결과 무효 | 1105 README 11.5절 |
FE-GATE-013을 시스템 컨테이너에서(gates.md 3절) |
desktop ssh 셸에서 user namespace가 막혀 provider 테스트 18건 실패. runner job 컨테이너에는 systemd·bubblewrap이 없어 사전 점검에서 실패(2026-11-08~11 run 56·80·81) | 1105/12-01, 1105 README 11.1절, 1106 README 1절 |
대조 허용치 < 여유(performance.md 5절) |
허용 1%(약 2 KB) > 남은 여유 1,873 B | 1105/15-02 |
예산을 올리는 것은 결정(performance.md 5절) |
초기 파일 수 26 → 32, 초기 JS 204,800 → 206,848 B | 1103 README 14.6절 #4, 1105 README 16.2절 D7, 1106 README 16.2절 D9 |
기준선은 합친 끝에서 다시 잰다(delegate.md 4.2절) |
브랜치마다 맞던 초기 JS 기록이 합친 빌드에서 허용치를 넘음 | 1106 README 16.3절 |
빠른 계층 quarantine 없음(testing.md 5절) |
소유자 결정 2026-11-03 | 1101 README 14절 |
3. 28개 관점의 지난 대표 발견
reference/review-criteria.md 5절 표의 관점마다 대표 발견이다.
| # | 대표 발견 | # | 대표 발견 |
|---|---|---|---|
| 1 | 1103/03-01 | 15 | 1103/13-03 |
| 2 | 0929/12-03 | 16 | 1103/13-03 |
| 3 | 1103/12-01, 1105/09-01 | 17 | 1105/07-01, 1105/16-02 |
| 4 | 1103 README 14.6절(매뉴얼만으로 기능 추가 재실험) | 18 | 1105/13-02 |
| 5 | 1105/13-01, 1105/12-01 | 19 | 1103/11-07, 1103/11-08 |
| 6 | 1105/01-01 | 20 | 1105/16-04 |
| 7 | 1105/13-01 | 21 | 1105/12-01, 1105/09-01 |
| 8 | 1105/12-01 | 22 | 1103/04-01 |
| 9 | 1103/14-01, 1105/14-01 | 23 | 1105/01-02 |
| 10 | 1103/10-02, 1103/05-01 | 24 | 1105/04-02 |
| 11 | 1103/05-01 | 25 | 1105/16-01 |
| 12 | 1103/05-01, 1105/12-04 | 26 | 1105/13-02 |
| 13 | 1105/15-02 | 27 | 1105/14-01 |
| 14 | 1103/15-01 | 28 | 1105/02-02 |
등급 판정 예(review-criteria.md 3절)의 출처: High·P1은 0929/03-03(상향), 1103/03-01, 1103/01-01. Medium·P1은 1103/02-06, 1103/12-01, 1103/15-01, 1105/09-01, 1105/12-01, 1105/13-01. Medium·P2는 0929/03-03 남은 부분. 헷갈리는 경우 표의 출처: 게이트가 항상 실패(1103/02-06, 1105/12-01, 1105/13-01), PASS 뒤 실패(1105/12-01, 1103/11-04), 문서가 코드와 다름(1103/14-02), 손 사본이 아직 같음(1103 README 5절 원인 4), 이미 다름(1105/01-02), 원래 상태에서만 맞음(1105/09-01).
4. 결함 패턴의 옛 번호
초안 부록의 P-NN → 지금 ID. 초안 장을 인용한 리뷰 문서·커밋이 있으면 이 표로 찾는다.
| 옛 | 지금 | 옛 | 지금 | 옛 | 지금 | 옛 | 지금 |
|---|---|---|---|---|---|---|---|
| P-01 | G1 | P-13 | T1 | P-25 | G12 | P-37 | C10 |
| P-02 | G2 | P-14 | S3 | P-26 | G13 | P-38 | C11 |
| P-03 | S1 | P-15 | T2 | P-27 | G14 | P-39 | S4 |
| P-04 | S2 | P-16 | T3 | P-28 | C1 | P-40 | S5 |
| P-05 | G3 | P-17 | T4 | P-29 | C2 | P-41 | S6 |
| P-06 | G4 | P-18 | T5 | P-30 | C3 | P-42 | W1 |
| P-07 | G5 | P-19 | T6 | P-31 | C4 | P-43 | W2 |
| P-08 | G6 | P-20 | T7 | P-32 | C5 | P-44 | W3 |
| P-09 | G7 | P-21 | T8 | P-33 | C6 | P-45 | W4 |
| P-10 | G8 | P-22 | T9 | P-34 | C7 | P-46 | B1 |
| P-11 | G9 | P-23 | T10 | P-35 | C8 | P-47 | B2 |
| P-12 | G10 | P-24 | G11 | P-36 | C9 | P-48, P-49 | B3, B4 |
5. 하네스 적용 기록 (2026-11-08)
- 새 세션이 처음 읽는 지침(루트
AGENTS.md+CLAUDE.md)의 전후 크기와 장부 줄은docs/ledger/estimates.jsonl의 taskfe-c-harness와 그 PR 본문에 있다. - 편집 훅의 경계 알림(N3)은 적용 시점
src/377개 파일(import 1,161개)에서 알림 0건이었다(거짓 양성 0). 규칙 파일을 그대로 읽어 정규식으로 판정하므로, 규칙이 바뀌면 훅도 따라간다. 정본은check:architecture다.