Files
clean-architecture-frontend…/docs/work/evidence.md
T
DongHyeonka 3524d6b00b docs(work): 작업 매뉴얼 docs/work/를 두고 개선 매뉴얼 초안을 흡수한다
프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 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
2026-11-08 17:27:39 +09:00

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단계의 손으로 적은 게이트 11개는 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 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 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다.