Files
clean-architecture-frontend…/docs/work/evidence.md
T
DongHyeonka 23df3203d8 docs(work): 정본이 정하는 검사 개수를 옮겨 적지 않는다
커밋 전 검사 8개, 통합 때 5개, 옛 게이트 11개처럼 config/ci/gates.json과 표가
정하는 개수를 문장에 옮겨 적었다. 표가 바뀌면 문장이 낡는다(문서 체계
검사의 숫자 복사 규칙). 개수를 빼고 표를 가리킨다.

검증: scripts/verify.sh docs rc=0.
2026-11-08 23:18:51 +09:00

100 lines
10 KiB
Markdown

# 근거와 이력
이 매뉴얼의 규칙이 나온 사건과 지난 리뷰 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](reference/review-criteria.md) 1절과 [improve.md](improve.md) 4.1절로 옮겼다. 옛 3단계의 "영역별로 서브에이전트를 병렬로"는 소유자 결정 2026-11-07에 맞춰 「결과만 받는 리뷰는 서브에이전트, 문서를 커밋하는 리뷰·파일을 바꾸는 위임은 하위 세션」으로 고쳤다. 옛 2단계의 손으로 적은 게이트 목록은 merge 단계 전부로 바꿨다(1105/12-03).
- `SPEC.md` 「공통 완료 기준」 9개를 [improve.md](improve.md) 5절로 옮겼다. 문서 체계 정리가 `SPEC.md`를 이력으로 옮길 수 있게 하려는 것이다(프론트 정리 프로그램의 총괄 결정, 2026-11-07).
### 1.1 초안 장 → 이 폴더
| 초안 | 옮긴 곳 | 바꾼 것 |
| --- | --- | --- |
| `README.md`(정본 표, 읽는 순서, 결정 M-1~M-10) | [README.md](README.md), 결정은 [reference/decisions.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](improve.md) 3·4절 | 스킬 표, 여섯 작업 종류의 단계와 완료 기준 |
| `02-review-criteria.md` | [reference/review-criteria.md](reference/review-criteria.md) | 28개 관점 표의 대표 발견 열은 이 문서 3절로 |
| `03-folder-module-structure.md`, `04-code-structure.md` | [reference/structure.md](reference/structure.md) | 한 문서로 합침 |
| `05-test-structure.md` | [reference/testing.md](reference/testing.md) | |
| `06-performance.md` | [reference/performance.md](reference/performance.md) | 1106 D9(예산 206,848 B)를 더함 |
| `07-verification-gates.md` | [reference/gates.md](reference/gates.md), [operate.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](reference/decisions.md) | 열린 결정 대기를 1106 기준으로 갱신(D8·D11 더함, D4·D5는 1106 README 7절에 없음) |
| `09-working-method.md` | [delegate.md](delegate.md), 멈춤 기준은 [improve.md](improve.md) 4.5절 | 「총괄이 자주 한 실수」는 delegate·improve 「자주 하는 실수」로 |
| `appendix-defect-patterns.md` | [reference/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 desktop 기록법(`gates.md` 3절) | ssh 셸에서 user namespace가 막혀 provider 테스트 18건 실패 | 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](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`의 task `fe-c-harness`와 그 PR 본문에 있다.
- 편집 훅의 경계 알림(N3)은 적용 시점 `src/` 377개 파일(import 1,161개)에서 알림 0건이었다(거짓 양성 0). 규칙 파일을 그대로 읽어 정규식으로 판정하므로, 규칙이 바뀌면 훅도 따라간다. 정본은 `check:architecture`다.