Files
clean-architecture-frontend…/docs/work/evidence.md
T
DongHyeonka f6e2560e4d
frontend-quality-gates / merge / static checks (pull_request) Successful in 1m49s
frontend-quality-gates / merge / tests (pull_request) Successful in 22m18s
frontend-quality-gates / merge / browser tests (pull_request) Successful in 6m54s
frontend-quality-gates / FE-GATE-014 / config-compatibility (pull_request) Skipped
frontend-quality-gates / FE-GATE-015 / immutable-release-candidate (pull_request) Skipped
frontend-quality-gates / external-vulnerability-provider (pull_request) Skipped
frontend-quality-gates / external-provenance-provider (pull_request) Skipped
frontend-quality-gates / promote-verified-immutable-candidate (pull_request) Skipped
frontend-quality-gates / deploy-promoted-release (pull_request) Skipped
frontend-quality-gates / FE-GATE-021 / runbook-boot-config (pull_request) Skipped
frontend-quality-gates / FE-GATE-022 / runbook-chunk-mismatch (pull_request) Skipped
frontend-quality-gates / FE-GATE-024 / runbook-telemetry (pull_request) Skipped
frontend-quality-gates / FE-GATE-025 / runbook-release-rollback (pull_request) Skipped
frontend-quality-gates / FE-GATE-028 / manual-accessibility-review (pull_request) Skipped
frontend-quality-gates / FE-GATE-026 / lab-performance (pull_request) Skipped
frontend-quality-gates / FE-GATE-019 / hosting-header (pull_request) Skipped
frontend-quality-gates / FE-GATE-023 / runbook-api-degradation (pull_request) Skipped
frontend-quality-gates / FE-GATE-018 / field-web-vitals (pull_request) Skipped
frontend-quality-gates / FE-GATE-017 / diagram-review (pull_request) Skipped
frontend-quality-gates / main / checker self-tests (pull_request) Skipped
docs: FE-GATE-013이 시스템 컨테이너에서 도는 것을 지침과 운영 문서에 적는다
문제: 작업 매뉴얼·루트 지침·스킬이 「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개 통과.
2026-11-12 19:52:09 +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단계의 손으로 적은 게이트 목록은 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의 task fe-c-harness와 그 PR 본문에 있다.
  • 편집 훅의 경계 알림(N3)은 적용 시점 src/ 377개 파일(import 1,161개)에서 알림 0건이었다(거짓 양성 0). 규칙 파일을 그대로 읽어 정규식으로 판정하므로, 규칙이 바뀌면 훅도 따라간다. 정본은 check:architecture다.