문제: 하네스에 분야 지식이 없다. QA·디자인/UX·디자인 시스템·React·폴더
구조·시험 환경·접근성·성능·보안의 이 repo 규칙(배럴 경계, 토큰 밖 색 금지,
axe 태그 범위, 예산, FE-GATE 실행법 등)은 문서와 검사기에 흩어져 있고,
여러 분야에 걸친 일을 누가 보고 어떻게 합치는지 정한 곳이 없다.
고른 방법(소유자 결정 2026-11-11 「W3 설계대로」, 백엔드와 같은 모양):
- 지식 스킬 fe-* 9개(.claude/skills/). paths를 걸어 그 분야 파일을 만질 때만
목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 → 검증 →
이 repo에서 정한 것 순서. 초안은 이 repo 문서만 본 서브에이전트가 썼고
glob 75개가 모두 파일에 걸리는 것을 확인했다.
- 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는
fe-structure를, verify-app은 fe-qa를 미리 싣는다(QA 탐색 차터).
- .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의
「함정」·「검증」을 보게 하는 두 줄.
- docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도(백엔드 repo로 가는 API
계약 차이는 총괄을 거침)·충돌·비용. 루트 AGENTS.md·CLAUDE.md 한 줄씩,
README 3절 4단계와 delegate.md 4.3절에 가리키는 말.
- 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 미리 싣는 스킬,
지식 스킬의 paths·설명 300자·금지어·절 순서·150줄·glob이 파일에 걸림,
명단이 모든 전문가를 담음, 규칙 목록에 expert-skills.
- 문서 PR #15와 겹치지 않게 docs/는 docs/work/만 건드렸다.
버린 대안: 분야마다 서브에이전트(QA·디자인·접근성 …). Anthropic
2026-10-22·2026-01-23·2026-04-07 글이 반대하고, 설명이 모든 세션에 든다.
위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이
병합돼야 받는다. fe-ux·fe-a11y의 paths는 템플릿에 기능 화면이 없어
src/presentation/**까지만 건다(기능이 생기면 넓힌다).
검증: scripts/verify.sh docs → rc=0, scripts/verify.sh hooks → 68건 통과.
새 시험은 조건을 깰 때마다 실패했다. desktop merge 단계는 이 커밋 뒤에 돈다.
main에 들어온 하네스 매뉴얼(docs/work/reference/gates.md, testing.md)이
「새 script·시험 파일이 게이트에 안 걸리면 check:ci가 실패한다」고 적는다.
이 PR의 f6b2b96c가 그 검사를 check:ci에서 떼어 main 단계 FE-GATE-029의
check:ci:gating으로 옮겼다. 두 줄과 생성기 주석 한 줄(merge_gate)을
고친다. 하네스 작업은 끝났고(PR #13 병합) 옮긴 명령을 가리키는 줄만
고쳤다.
검증(desktop): verify:documentation, test:unit.
main(d1b9c087)에 하네스 PR #13이 들어가 루트에 `AGENTS.md`, `.claude/`,
`.gitattributes`가 생겼다. 이 브랜치는 그 셋을 루트 등록부에 optional로
미리 적어 두었다.
충돌 둘을 풀었다.
- `scripts/lib/removal-fixture.ts`: main은 문서 복사 목록에 `AGENTS.md`를
더했고 이 브랜치는 그 목록을 등록부의 `fixture-documents` 집합으로
바꿨다. 등록부의 `AGENTS.md` 항목에 그 집합을 적었다.
- `tests/unit/template-feature-removal-documents.test.ts`: main은 문서
목록에 `AGENTS.md`와 옛 a11y 기록 폴더를 더했다. a11y 기록은 이
브랜치에서 `docs/`로 옮겼으므로 `AGENTS.md`만 남겼다.
등록부의 `AGENTS.md`·`.claude`·`.gitattributes`는 이제 추적되는 항목이라
optional을 빼고 역할을 실제 내용으로 고쳤다. 추적되는 루트 항목과
등록부 항목이 서로 남는 것 없이 같다.
검증(desktop): 커밋별 5검사와 merge 게이트 14개, verify:documentation.
desktop(트리 04bb0e0e)에서 두 가지가 실패했다.
- FE-GATE-010·020: check:adapter-inventory가 "total does not equal 143
tracked files"로 멈췄다. src/adapters의 AGENTS.md·CLAUDE.md 두 행은
더했지만 INVENTORY.md 끝의 합계 줄(141/141)을 고치지 않았다.
- scripts/verify.sh parts FE-GATE-013: verify:reproducible-build,
build:release-candidate, verify:local-evidence가 "missing required CI build
environment: SOURCE_DATE_EPOCH"로 실패했다. ci:gate는 HEAD에서 이 값을
만들지만 parts·script는 명령을 직접 부른다.
합계를 143/143으로 고치고, ci_env가 HEAD 커밋 시각으로 SOURCE_DATE_EPOCH를
준다(ci:gate와 같은 값).
검증: python3 -m unittest discover -s scripts/tests 통과(ci_env가 HEAD
SHA·커밋 시각·digest 꼴 이미지를 주는 시험 추가). desktop 재실행은 이
커밋 트리에서.
커밋 전 검사 8개, 통합 때 5개, 옛 게이트 11개처럼 config/ci/gates.json과 표가
정하는 개수를 문장에 옮겨 적었다. 표가 바뀌면 문장이 낡는다(문서 체계
검사의 숫자 복사 규칙). 개수를 빼고 표를 가리킨다.
검증: scripts/verify.sh docs rc=0.
계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는
보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다.
src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일,
그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그
폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든
폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에
@AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은
책을 읽는다(백엔드와 같은 짝).
- .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다.
- scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를
본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다.
- docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters
아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다.
- 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의
양식을 가리킨다.
버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md
없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만
읽어 백엔드와 갈린다).
위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면
이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture).
검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200),
python3 -m unittest discover -s scripts/tests 62건 통과.
하네스 자료는 레이어 규칙·훅·스킬과 함께 비전(세 문장)과 문제 정의(고객의
말 그대로, 하지 않는 것, SMART 성공 기준)를 빈 양식으로 템플릿에 두라고
한다. 프론트에는 둘 다 없었다.
claude-harness template/docs/의 두 파일을 옮긴다. 프로젝트 이름 자리표시자는
빼고, 결정 기록 위치는 이 repo의 docs/architecture/decisions/로 바꿨다.
루트 AGENTS.md가 한 줄로 가리킨다(다음 커밋).
위험·한계: 채울 것 자리는 소유자 몫이라 비워 둔다. 문서 검사 범위
(docs/README.md 1절) 밖이다.
검증: python3 -m unittest scripts/tests/test_claude_setup.py 통과.
PR B는 정리 3·4단계 브랜치(chore/layout-3-merge) 위에 쌓았다. 그 브랜치에
더한 커밋 16eb200f(하네스가 더할 .gitattributes를 등록부에 optional로
적음)를 받는다. PR B 커밋은 다시 쌓지 않아 CHANGELOG의 해시가 그대로다.
하네스 PR(#13)이 루트에 `.gitattributes`(작업 장부 파일의 병합 규칙)를
더한다. 이 PR이 먼저 들어가고 그 PR이 나중에 들어가면 등록부에 없는
루트 항목이 생겨 `tests/unit/repository-layout.test.ts`(R1)가 실패한다.
`AGENTS.md`·`.claude`처럼 optional 항목으로 미리 적는다. 없으면 고르는
집합이 없어 다른 검사에 영향이 없다.
검증(desktop): test:unit, check:ci, verify:documentation.
정리 단계 미출시 절에 CI 재편(merge job 셋, main 단계 FE-GATE-029,
계약 기준선 삭제, F3 판정 표)을 더한다. 다운스트림이 할 일 13·14(기준선
파일 삭제, merge job 이름과 필수 검사), 옮긴 뒤 확인 한 줄, 계약 표 두
줄, 알려진 제한 한 줄(Gitea runner 실행 미확인)을 적었다.
위험: 다운스트림에 적용해 보지 않았다.
검증(desktop): changelog-review-ids를 포함한 test:unit.
Refs: design-docs repo-structure/03-ci.md 7.3절
scripts/check-*.ts 30개(6,351줄)가 게이트 명령의 상당수를 차지한다.
각각을 ESLint 규칙, dependency-cruiser 규칙, vitest 시험으로 옮길 수
있는지 판정 표로 남긴다(design-docs repo-structure/03-ci.md 7.3절 F3).
코드는 바꾸지 않는다.
판정: 시험 8, 일부 이전 9, 스크립트 유지 11, ESLint 규칙 1, 지움 1
(정리 3단계). 위험이 낮고 효과가 큰 후보 5개와, 옮길 때 같이 고칠
증거 계약·drill 목록을 적었다.
위험: 줄 번호는 판정 시점 `ad3a071f` 기준이다. 판정 중에 찾은 가짜 검사
2개(`check-design-system.ts`, `check-diagnostics.ts`의 fixture 표식 검사)는
고치지 않았다.
검증: 문서만. 스크립트를 읽어 판정했고 실행하지 않았다.
Refs: design-docs repo-structure/03-ci.md 7.3절 F3
merge 단계(=PR)가 변경이 아니라 검사기 자신을 시험하는 명령까지 돈다.
검사기가 나쁜 입력을 거부하는지 보는 `*:fixture` 명령 15개, 모든 시험
파일과 검증 script가 게이트에 걸렸는지 보는 ungated 검사, CI 계약의
개수·해시 기준선(`config/ci/contract-baseline.json`)이다. 기준선은 게이트
명령 하나를 더하거나 빼도 OWNER·REASON을 붙여 다시 받아야 했다.
소유자 결정(2026-09-16)은 개수·배선 검사를 main 단계에 두는 것이다.
고른 방법(design-docs repo-structure/03-ci.md 7.3절 F2, README.md 3.3절,
소유자 승인 2026-11-07):
- 새 게이트 FE-GATE-029 `checker-self-tests`, 새 단계 `main`
(`MAIN_READY`, 승격을 막지 않는다), 새 job `main_gate`. 브랜치 push와
`workflow_dispatch`(stage=main)에서만 돈다. PR과 태그에서는 돌지 않는다.
- FE-GATE-001·005·008·010·013의 `*:fixture` 명령 15개와 그 증거
산출물 10개를 FE-GATE-029로 옮긴다.
- `check:ci`의 ungated 검사를 `scripts/check-ci-gating.ts`
(`check:ci:gating`)로 떼어 FE-GATE-029에 둔다. `check:ci`는 계약·
workflow 검사만 PR에서 돈다.
- 기준선 파일, `update:ci-contract-baseline`, 그 검사를 지운다(소유자
결정). 계약 모양은 ci-gates.ts의 의미 검사가 지킨다. 개수를 고정하던
단위 시험의 개수 단언도 뺐다.
남긴 것: 음성 타입 fixture(`check:types:fixtures`, FE-GATE-003)는
이름이 `*:fixture`여도 merge에 둔다. 검사기가 아니라 src의 포트·계약
타입을 시험한다. `TelemetryPort.emit`을 넓히는 변경을 PR에서 막는다(정리
3단계 9.3절 변이로 확인). merge 단계 명령 참조 64 → 49.
위험: 검사기를 망가뜨린 PR은 merge를 통과하고 main에서 빨개진다. 그
대가로 PR이 검사기 자기 시험을 기다리지 않는다(설계 7.5절의 같은 교환).
FE-GATE-029의 명령이 앞 게이트 산출물 없이 새 checkout에서 도는지는
desktop에서 따로 확인했다(PR 본문).
검증(desktop): check:ci, check:ci:gating, check:types, CI 시험 통과.
merge 단계·FE-GATE-029 실행 결과는 PR 본문에 적는다.
Refs: design-docs repo-structure/03-ci.md 7.3·7.4절, README.md 3.3절
`docs/README.md` 표가 수동 a11y 기록을 아직 `artifacts/tests/a11y-manual/`로
가리킨다. 기록은 `docs/accessibility/route-reviews/`로 옮겼다(79dc945a).
`verify:documentation`은 `.gitignore`가 무시하는 경로를 생성 출력으로 보고
넘겨서 이 줄을 잡지 못했다.
검증(desktop): verify:documentation, test:unit.
merge 단계가 게이트마다 job 하나(행렬 14개)라서 PR마다 checkout,
setup-node, `pnpm install`을 14번 하고 브라우저 설치를 2번 한다. Gitea
runner는 소유자 기계 한 대다. 사례(Vite 등)는 설치를 job당 한 번으로
묶는다(design-docs repo-structure/03-ci.md 3.5절).
고른 방법(03-ci.md 7.3절 F1, 소유자 승인 2026-11-07):
- job 종류 `gate-sequence`를 더한다. job 하나가 게이트 여럿을 차례로
돈다. 게이트마다 `FE-GATE-NNN / <이름>` 단계이고 `if: !cancelled()`라
앞 게이트가 실패해도 다음 게이트가 돈다(행렬의 fail-fast: false와 같다).
- merge job 셋: `merge_static`(001·002·003·010·011·012, 소스를 읽고
빌드하는 검사), `merge_test`(004·005·006·007·013·020, 시험),
`merge_browser`(008·009, 브라우저 설치). release 단계는 셋을 모두
기다린다. 게이트 id·명령·증거·승격 공식은 그대로다.
- 증거 업로드는 job마다 하나(`merge-static-<run>` 등)다.
버린 것: 행렬을 두고 `pnpm install`만 캐시하는 방법. runner 한 대에서는
job 수만큼 checkout과 준비가 남는다. 게이트를 job 하나에 모두 넣는
방법은 브라우저 설치를 모든 게이트가 기다린다.
위험: 한 job 안의 게이트가 같은 작업 공간을 쓴다. 앞 게이트의 산출물이
뒤 게이트에 남는다. desktop의 merge 단계 실행(게이트를 한 checkout에서
차례로 도는 것)과 같은 조건이라 그 결과로 확인했다. 실제 Gitea runner의
`!cancelled()` 해석은 Actions를 켠 뒤 확인한다.
검증(desktop): check:ci, check:types, CI 시험 4파일 통과. 합치기
전후 merge 단계 게이트별 결과 비교는 PR 본문에 적는다.
Refs: design-docs repo-structure/03-ci.md 3.5·7.3·7.4절, README.md 3.3절
정리 단계 미출시 절에 3단계(합치기)와 4단계(배치 규칙 검사)를
더한다. 다운스트림이 할 일 7~12(음성 타입 fixture 기대 줄, 지운
tsconfig, a11y 기록과 스키마 이동, 루트 등록부, CI 계약 기준선)와 계약
표 세 줄, 알려진 제한 둘(R2가 보는 범위, R5의 문자열 검색)을 적었다.
위험: 다운스트림에 적용해 보지 않았다(절의 알려진 제한과 같다).
검증(desktop): `tests/unit/changelog-review-ids.test.ts`를 포함한
test:unit.
Refs: design-docs repo-structure/04-frontend-layout.md 9.2절
이 대화를 모르는 서브에이전트에게 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 통과.
cold-read 시험에서 두 곳이 막혔다. script 단계가 인자를 넘기지 못해
test:sample-removal -- --feature=<id>를 돌릴 수 없었고, desktop에서
만든 파일(create:feature, 초기 JS 기록 다시 쓰기)을 노트북으로 가져올
길이 없었다. dry-run은 공백 든 인자를 실제와 다르게 보였다.
- script <이름> -- <인자…>: 인자는 script가 하나일 때만 넘긴다.
- exec -- <명령…>: 한 테스트 파일이나 package script가 아닌 node 스크립트.
- 원격에서 바뀐 파일은 로그 폴더의 changes.patch에 남고, --apply-back이면
노트북 작업 트리에 얹는다.
- VERIFY_SNAPSHOT=1이면 artifacts·dist·test-results를 snapshot/에 복사한다
(리뷰어가 함께 읽는 사본). VERIFY_INSTALL=0은 설치를 건너뛴다(시험용).
- dry-run이 인자를 %q로 보인다.
- 원격 호출은 단계 다음에 --on here를 둔다. 뒤에 두면 `--` 뒤 명령
인자가 되어 원격이 자기를 다시 원격으로 보냈다(시험에서 잠금 교착으로
드러났다).
- 원격 준비가 일찍 실패해도 /tmp의 패치 파일을 지운다.
위험·한계: --apply-back은 노트북 작업 트리가 원격 기준과 다르면 패치가
얹히지 않는다. 그때는 rc=4와 원격 패치 경로를 알린다.
검증: python3 -m unittest scripts/tests/test_verify.py 통과(인자 전달,
exec, 잘못된 인자 10가지가 원격 호출 0, 가짜 ssh로 원격에서 만든 파일
둘을 돌려받음, 바뀐 것 없는 단계의 changes.patch는 빈 파일).
template-contract-documents.test.ts가 README 표를 찾으려고
docs/superpowers 경로를 문자열로 적었다. deletable-history-documents.
test.ts는 코드·테스트가 지워도 되는 문서를 가리키면 실패하므로,
desktop merge 단계의 FE-GATE-005에서 이 두 줄로 실패했다.
경로를 조각으로 이어 만든다(그 시험 자신과 같은 방법). 시험이 보는
것은 그대로다.
검증: desktop FE-GATE-005(트리 ada4015c)의 실패 줄이 이 파일 15·35줄
이었다. 고친 뒤 결과는 PR 전 merge 단계에서 본다.
소유자가 2026-11-07에 지적한 것(매뉴얼이 생긴 뒤에도 남은 샘플, 역할이
겹치는 루트 폴더, 0파일 검사, 문서 속 인프라 설정)은 매뉴얼과 리뷰가
먼저 잡아야 했다. 지금은 그 규칙이 글로도 검사로도 없다. 그래서 같은
지적이 다시 나와도 게이트가 모른다.
고른 방법(design-docs repo-structure/04-frontend-layout.md 11절, 기계
검사가 「예」인 규칙을 표의 게이트 칸대로):
- R4·R5 `tests/unit/example-feature-rules.test.ts`(FE-GATE-005): 샘플
목록은 FE-GATE-020의 `test:sample-removal`(인자 없이, 빌드와 test:all
포함)이 증명한다. 목록 샘플의 기능 ID·라우트가 visual·e2e의 `goto`,
gates.json 산출물 경로, `config/scale/`에 나오면 실패한다. 템플릿
목록은 비어 있어 가짜 샘플로 판정 함수를 시험한다.
- R6·R7(문서) `verify:documentation`(FE-GATE-017): `docs/manual/`이 목록
샘플 경로를 가리키면, 현재 문서에 ```nginx```·```hcl``` 블록이나
`kind: Deployment` 같은 매니페스트 줄이 있으면 실패한다. 이력 폴더는
보지 않는다. 산출물 `documentation-review.json`에
`layoutRuleViolations`를 더했다.
- R7(파일)·R9 `tests/unit/repository-layout.test.ts`(FE-GATE-005):
nginx·Terraform·Helm·Kustomize 파일과 Kubernetes 매니페스트 YAML이
추적되면 실패. 옵션이 같은 tsconfig 쌍이 있으면 실패.
- R3은 `tests/unit/tracked-artifacts.test.ts`, R8은 앞 커밋의
`check-typecheck-inputs.ts`·`check-type-fixtures.ts`가 맡는다. R10의
기계 몫(루트 *.md 등록)은 R1이다.
- 매뉴얼 03에 E절(R1~R10 규칙과 검사, 루트 항목을 더하는 순서)과 C절
「Web Worker를 들일 때 tsconfig 더하기」(결정 D4)를 더했다.
위험: R5는 문자열 검색이라 샘플 ID를 다르게 쓴 대상(예: 라우트 경로를
조립하는 spec)은 놓친다. R7 문서 검사는 코드 블록 언어 태그와 매니페스트
줄로만 본다. R13(리뷰 가이드)은 design-docs 몫이라 넣지 않았다.
검증(desktop): 이 커밋에서 test:unit, check:types, check:ci, lint,
verify:documentation, check:architecture를 돌렸다.
Refs: design-docs repo-structure/04-frontend-layout.md 11절, README.md 3.4절
루트 항목 하나를 옮기려면 코드 7곳의 루트 경로 목록을 같이 고쳐야
했다(복사 대상, 비밀값 검사 범위, 공급망 시험의 필수 입력, 이력 문서
검사, 규모 입력, vite 입력, TS 전용 규칙). 서로 다른 부분집합이고 한
곳에서 선언하지 않았다. 목록이 갈라져 공급망 생성이 깨진 적도 있다
(removal-fixture.ts 주석). 루트에는 JSON Schema 5개만 담은 `schemas/`가
`config/` 옆에 따로 있었다. `artifacts/`(출력 폴더)에는 사람이 쓴 수동
a11y 기록이, `config/hosting/`(호스트 계약)에는 시험 fixture가 섞였다.
고른 방법(design-docs repo-structure/04-frontend-layout.md 9.2절 3단계,
11절 R1·R2, 소유자 승인 2026-11-07):
- `config/repository-layout.json`이 루트 항목마다 종류·역할·읽는 곳과
들어가는 목록(`sets`, 항목 안 경로는 `setPaths`)을 적는다.
`scripts/lib/repository-layout.ts`가 읽고 검증한다. 6곳은 이름 붙은
집합을 고른다. JSON인 비밀값 검사 정책은 집합의 사본을 두고 시험이
같은지 본다(정책 파일은 릴리스 후보에 실려 형식을 바꾸지 않았다).
공급망 시험의 필수 입력 목록은 그 시험으로 대신한다.
- `tests/unit/repository-layout.test.ts`: 등록부에 없는 루트 항목이
추적되면 실패(R1). 7곳이 등록부 모듈을 쓰고 루트 이름 둘 이상의
문자열 배열을 갖지 않는지(R2).
- `schemas/artifacts/` → `config/schemas/artifacts/`, recipe 카탈로그
스키마 → `config/schemas/recipes/`. 정책 입력 순서(ASCII)에 맞춰
`config/schemas/`가 `config/security/` 앞에 온다.
- 수동 a11y 기록 3개 → `docs/accessibility/route-reviews/`. `artifacts/`는
`.gitkeep`만 추적한다. 기록은 단위 시험이 읽어서 drill 사본에도
복사한다(`fixture-copy` 집합의 `docs/accessibility/route-reviews`).
- `config/hosting/response-headers.fixture.json` →
`tests/fixtures/hosting/response-headers.json`.
버린 것: 비밀값 검사 정책이 집합 이름을 참조하게 바꾸는 방법. 정책
파일은 릴리스 후보와 로컬 증거 평가가 읽는 형식이라 바꾸면 릴리스
증거 계약이 바뀐다. 루트 항목이 지워졌는데 등록부에 남는 경우는
시험하지 않았다. drill 사본은 일부만 복사해 그 방향을 볼 수 없다.
그런 항목은 그 집합을 쓰는 곳(복사, 비밀값 검사)에서 실패한다.
위험: 하네스 작업(fe-c)이 더할 `AGENTS.md`·`.claude/`를 미리 등록했다
(optional). 등록부가 이력 문서(`SPEC.md`)와 `CLAUDE.md` 이름을 적어서
이력 문서 검사에서 등록부 파일은 뺐다. 다운스트림은 자기 루트 항목을
등록부에 더해야 한다(CHANGELOG). CI 계약 기준선을 다시 받았다(a11y
기록 산출물 id·경로).
검증(desktop): 아래 4단계 커밋까지 쌓은 트리에서 test:unit,
check:types, check:ci, lint, verify:documentation을 돌렸다(그 커밋에
적음). 이 커밋 단독으로 test:unit·check:ci·check:types를 돌렸다.
Refs: design-docs repo-structure/04-frontend-layout.md 2.4·9.2·11절, README.md 3.4절
음성 타입 fixture마다 옵션이 같은 tsconfig 하나, package script 하나,
게이트 명령 하나가 있었다(23벌). 옵션은 모두 같고 파일 하나만 달라서
fixture를 더할 때마다 세 곳을 같이 고쳤다. `tsconfig.recipes.json`도
`tsconfig.test.json`과 lib가 같고 types만 하나 적었다.
`tsconfig.web-worker.json`은 `files: []`로 0파일을 검사하고 통과했다
(2026-09-25 리뷰가 기록, FE-GATE-003이 통과로 보였다).
고른 방법(design-docs repo-structure/04-frontend-layout.md 5.3절 (가),
소유자 승인 2026-11-07):
- fixture 첫 줄에 기대(`// expect: TS2322`, `// expect: pass`)를 쓰고
`scripts/check-type-fixtures.ts`가 fixture마다 `.tmp/type-fixtures/`에
한 파일 tsconfig를 써서 tsc를 돈다. 판정은 run-ci-gate.ts가 명령마다
하던 것과 같다(exit 1과 `error TS<code>:`). 결과를 fixture별로 출력한다.
기대 줄이 없는 fixture와 fixture 0개는 실패한다.
- recipes는 `tsconfig.test.json` include로 옮긴다.
- web-worker tsconfig와 script는 지운다(결정 D4). Worker를 들일 때 더하는
단계는 매뉴얼 03에 쓴다(뒤 커밋).
- `scripts/check-typecheck-inputs.ts`를 `check:types` 끝에 둔다. package
script가 tsc에 넘기는 tsconfig마다 이 repo 파일이 1개 이상인지 본다.
`files: []` tsconfig가 통과로 보이던 구멍을 막는다(R8).
버린 것: TypeScript API로 한 프로세스에서 돌리는 방법. 이 repo의
TypeScript 7.0(네이티브판)은 JS API를 싣지 않는다. 위반마다
`@ts-expect-error`를 쓰는 방법(5.3절 (나))은 오류 코드 고정을 잃는다.
위험: recipe가 이제 `vite/client` 타입이 있는 프로그램에서 검사된다.
recipe가 `import.meta.env`를 쓰면 전에는 실패했고 이제는 통과한다
(복사한 제품도 Vite라 가치가 작다, 설계 5.1절). CI 계약 기준선을 다시
받았다(명령 99 → 76).
검증(desktop): `check:types:fixtures` 23개 PASS, 각 fixture의 기대 코드가
출력에 그대로 나온다. `TelemetryPort.emit` 인자를 `string`으로 넓히는
변이(2026-09-25 리뷰 07-05)에서 `invalid-diagnostics-port.ts`가 TS2578로
FAIL, 실행기 rc=1. 되돌린 뒤 작업 트리 0줄. `check:types` rc=0
(Typecheck inputs: app 379, node 312, service-worker 22, test 915).
Refs: design-docs repo-structure/04-frontend-layout.md 5.3·9.2·9.3절, README.md 3.4절 D4
복사한 프로젝트가 이 묶음을 받을 때 할 일(루트 CLAUDE.md를 걸러 내지
않기, .claude/ 무시 규칙, 장부 비우기)과 문서 검사 범위가 넓어진 계약
변경을 적는다. 다른 정리 단계 절과 줄이 겹치지 않게 절을 따로 둔다.
검증: 커밋 칸의 해시는 origin/main 8327e221 위로 rebase한 뒤의 값이다.
README의 지워도 되는 파일 표가 루트 CLAUDE.md를 "템플릿 repo 자신의
리뷰 지시, 자기 것으로 바꿔라"로 분류했다. 소유자 결정(2026-11-07 Q4)은
루트 지침을 템플릿 계약으로 정했다. 그리고 AGENTS.md와 docs/work/는
verify:documentation 범위 밖이라 그 안의 경로·script·게이트 ID가 틀려도
아무 검사도 알리지 않는다.
- README: 문서 절에 AGENTS.md와 docs/work/ 포인터를 더하고, 지워도 되는
표에서 CLAUDE.md 행을 빼고 docs/ledger/estimates.jsonl("줄을 비운다")을
넣는다.
- docs/README.md 1절: ../AGENTS.md, work/, work/reference/를 링크한다.
- tests/unit/template-contract-documents.test.ts: 지워도 되는 표에
AGENTS.md·CLAUDE.md·.claude·docs/work가 없고, 1절이 셋을 링크하는지
본다. 표는 제목이 아니라 docs/superpowers/ 행으로 찾아 제목을 옮겨도
돈다. 문서를 읽으니 REMOVAL_FIXTURE_DOCUMENT_TESTS에 올렸다.
- deletable-history-documents.test.ts: CLAUDE.md 패턴을 뺀다(이제 지워도
되는 문서가 아니다).
- 제거 드릴의 문서 사본(REMOVAL_FIXTURE_DOCUMENT_TARGETS)과
template-feature-removal-documents.test.ts의 사본에 AGENTS.md를 더한다.
사본 안에서 검사기를 돌리므로, 1절이 링크한 AGENTS.md가 없으면
FE-GATE-020과 그 단위 시험이 실패한다.
버린 대안: AGENTS.md를 링크하지 않고 백틱으로만 적기. 검사가 빠진다.
위험·한계: 문서 체계 세션이 README를 한국어로 옮기면 표 제목이 바뀐다.
새 시험은 행으로 찾지만, verify-documentation-readiness.ts의 지운 이력
목록은 영어 제목을 읽으니 그 세션이 같이 고친다.
검증: 새 시험은 README·docs/README.md를 고치기 전 트리에서 둘 다
실패했고(desktop test:unit), 고친 뒤 통과한다. verify:documentation과
merge 단계는 PR 전 합친 트리에서 돌린다.
Refs: design-docs harness/01-harness-design.md 4.4절·13절 Q4
작업마다 착수할 때의 예측과 끝날 때의 실측을 남길 곳이 프론트에 없었다.
소유자 결정(2026-11-07 Q11)은 repo마다 docs/ledger/estimates.jsonl이다.
docs/ledger/README.md(백엔드와 같은 형식)와 estimates.jsonl을 두고,
여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes가
merge=union을 준다. 첫 줄은 이 작업(fe-c-harness)의 착수 예측이다.
위험·한계: 복사한 프로젝트는 템플릿의 줄을 받는다. README 지워도 되는
표에 "줄을 비운다"로 적는다(뒤 커밋).
검증: python3 -m unittest scripts/tests/test_ledger.py 통과.
Refs: design-docs harness/01-harness-design.md 10절·13절 Q11
desktop에서 게이트를 돌리는 법이 문서와 세션마다 다른 손 절차였다
(checkout 바꾸기·되돌리기, CI env 넣기, runner 스크립트 복사). 같은 빈틈이
되풀이됐고, 공유 checkout의 브랜치를 바꾼 채 두는 위험이 있었다.
scripts/verify.sh <단계>는 claude-harness template/scripts/verify.sh의
운반부를 쓰고 단계를 채운다.
- 단계: config/ci/gates.json의 stage id(merge·release·production·field·
documentation)는 그 gateIds 전부를 ci:gate로, gate <ID>…, parts <ID>(그
게이트의 명령을 하나씩 끝까지, FE-GATE-013 진단용), script <이름>…,
docs·hooks(노트북). stage는 실패가 있어도 끝까지 돌고 게이트마다 rc와
초를 남긴다.
- desktop: 지금 트리를 기준 커밋에 대한 패치로 보내 공유 checkout에서 새
worktree를 만들고, 트리 해시를 맞춘 뒤 commit-tree로 깨끗한 HEAD를 만든다.
CI=true pnpm install --frozen-lockfile --offline 뒤 flock 잠금 아래 CI
env(CI, VITE_COMMIT_SHA, VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE)로
돌리고, /tmp/claude-gates/<이름>/에 summary·로그·게이트 산출물·
status-after를 남긴 뒤 worktree를 지운다. push하지 않는다.
- 잘못된 단계·게이트는 desktop에 보내기 전에 노트북에서 거절한다.
버린 대안: 공유 checkout의 브랜치를 잠금 안에서 바꾸고 되돌리기(지금 손
절차). 다른 세션의 checkout을 건드리고, 끝나지 않으면 바뀐 채 남는다.
위험·한계: 새 worktree의 오프라인 설치는 desktop pnpm store에 의존한다.
없으면 온라인 설치로 넘어간다. CI workflow가 아직 이 스크립트를 부르지
않는다(CI 재편 몫).
검증: python3 -m unittest scripts/tests/test_verify.py 통과(stage마다
계약의 gateIds, parts의 명령, 잘못된 인자는 원격 호출 0, 가짜 ssh로
패치 → 같은 트리 해시 → 로그 → worktree 정리, 없는 원격 repo는 rc=4).
desktop에서 실제 운반을 한 번 돌려 트리 해시 일치와 worktree 정리를 봤다.
Refs: design-docs harness/01-harness-design.md 6절
경계 위반, 늘어난 skip·only, 작업 매뉴얼 규칙 위반은 desktop 게이트에서야
드러났고, desktop 검증 없이 턴을 끝내도 아무것도 알리지 않았다.
scripts/hooks/hooks.py(백엔드 hooks.py와 같은 모양, 표준 라이브러리와
git만)를 .claude/settings.json에 단다.
- N3: src TypeScript를 고치면 import를 .dependency-cruiser.json의 forbidden
규칙(path·pathNot·$1)에 그대로 대 본다. 규칙 파일을 읽으므로 규칙이
바뀌면 따라간다.
- N6: 테스트에 .skip·.only·.fixme·.todo가 마지막 커밋보다 늘거나, 예산·
기준선·ungated 목록·스냅숏을 고치면 알린다.
- N2: .md를 고치면 scripts/check-work-docs.py의 실패 줄을 알린다.
- N5: desktop만 확인할 수 있는 파일을 고친 뒤 desktop 실행이 없으면 턴
끝을 한 번 막고 이유를 준다.
모두 넛지다. repo 안 편집에 되돌릴 수 없는 것이 없어 차단 훅은 없다.
고른 방법: 노트북에서는 정적 검사만 하고 포맷·린트·타입은 desktop
scripts/verify.sh에 둔다(brief, 2026-11-08). 설계 13절 Q6은 편집 훅에서
한 파일 eslint를 골랐지만, 프론트 eslint는 pnpm·node_modules가 필요해
"pnpm은 desktop에서만" 규칙과 부딪친다.
위험·한계: N3는 정규식으로 import를 뽑아 주석 속 따옴표 같은 드문
모양을 놓칠 수 있다. 정본은 check:architecture다. 훅 시험은 아직 CI
workflow가 부르지 않는다. 훅은 세션 시작에 읽혀 이 세션에서는 돌지
않았다.
검증: python3 -m unittest scripts/tests/test_hooks.py 26건 통과. 실제
규칙과 src 377개 파일에서 N3 알림 0(거짓 양성 시험). 조건 하나씩 끈
변이 10개를 모두 시험이 잡았다.
Refs: design-docs harness/01-harness-design.md 5.2·5.3절
Claude Code 세션이 테스트·문서·adapter·게이트 기준·기능 폴더를 고칠 때
읽을 규칙이 루트 한 파일에 섞여 있었고, desktop 실행과 새 기능 절차를
부르는 스킬, 결과만 받는 리뷰어 정의가 없었다.
- .claude/rules/: tests, docs, adapters, gates-and-budgets, features.
paths로 그 파일을 열 때만 읽힌다.
- .claude/skills/: desktop-gates(scripts/verify.sh로 desktop에서 돌리기),
new-feature(create:feature부터). 소유자 결정대로 모델이 부르고, 설명에
발동 조건을 문단으로 쓴다. 본문은 정본 playbook을 가리킨다.
- .claude/agents/: arch-reviewer(경계 규칙), verify-app(desktop에서
빌드·브라우저 확인), code-simplifier. 쓰기 도구가 없다.
- .claude/settings.json: 하네스 플러그인 harness@claude-harness를 켜고
실제 .env 읽기·쓰기를 막는다. Agent deny는 두지 않는다.
- .gitignore: .claude/는 이 넷만 추적하고 worktree·훅 상태·
settings.local.json은 무시한다.
버린 대안: Agent deny 유지(소유자 결정 2026-11-07 Q5가 풀었다), 스킬을
사용자 호출 전용으로(Q9가 모델 호출을 골랐다).
위험·한계: 규칙 paths는 지금 있는 파일로 시험하지만 Claude Code가 실제로
읽는지는 이 세션에서 보지 않았다(설정은 세션 시작에 읽힌다).
검증: python3 -m unittest scripts/tests/test_claude_setup.py 통과
(서브에이전트 쓰기 도구 없음, 스킬 설명 길이와 발동 조건, 규칙 paths가
가리키는 파일 있음).
Refs: design-docs harness/01-harness-design.md 13절 Q3·Q5·Q9
루트에는 리뷰 기준만 담은 CLAUDE.md(26줄)가 있었다. 꼭 지킬 경계 규칙,
지도, 검증 진입점, 맡은 일 라우터가 없었고, "서브에이전트를 병렬로"는
소유자 결정(2026-11-07)과 맞지 않았다.
AGENTS.md(35줄)에 무엇인가 · 꼭 지킬 것 5 · 지도 · 맡은 일 · 검증 ·
일하는 방식을 둔다. CLAUDE.md는 @AGENTS.md와 Claude 전용 줄(10줄)이다:
settings·훅, 하네스 플러그인과 비대화형 설치 두 명령, 규칙·스킬·
서브에이전트 위치, 리뷰 기준이 옮겨 간 곳, 소유자 환경. 리뷰 기준과
전체 리뷰 절차는 docs/work/reference/review-criteria.md와
docs/work/improve.md 4.1절로 옮겼다.
scripts/check-work-docs.py는 백엔드 검사기를 옮긴 것이다: 지도 40줄,
CLAUDE.md 15줄, README 80줄, playbook 150줄, 진입 경로 350줄, 9절 뼈대,
진입 문서의 이력 ID 0, 상대 링크. 이력 패턴에 이 repo의 꼴(1105 README,
P-43·O-12·D-14)을 더했다. 표준 라이브러리만 써서 노트북에서 돈다.
버린 대안: CLAUDE.md만 두기(다른 에이전트가 못 읽는다), 심볼릭 링크
(Claude 전용 줄을 둘 수 없다).
위험·한계: 지도 40줄은 자료와 백엔드에 맞춘 값이다. brief 상한 80보다
좁다.
검증: python3 scripts/check-work-docs.py rc=0,
python3 -m unittest scripts/tests/test_check_work_docs.py 통과.
Refs: design-docs harness/01-harness-design.md 4.3절·13절 Q1·Q2
프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 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
샘플 라우트를 지워 라우트가 3개가 되자 FE-GATE-003의 route-runtime 음성 fixture가
TS2740 대신 TS2739를 내 기대 진단과 어긋났다. tsc는 빠진 키가 많으면 TS2740,
적으면 TS2739를 낸다. fixture가 정확히 한 라우트만 빼도록 바꿔 어느 라우트 수에서나
TS2741이 나오게 하고 기대 진단을 맞췄다.
정리 1단계(PR #11)와 2단계(샘플 역할 이전과 삭제)가 CHANGELOG에 없다.
다운스트림은 이 절을 보고 샘플 사본 처리와 기준선 재승인을 한다.
미출시 절 「48c7695b → 정리 단계」를 맨 위에 더했다. 「먼저 할 일」에
샘플 사본을 지우거나 자기 기능으로 옮기는 법, 레지스트리·CI 계약
기준선과 초기 JS 기록을 다시 받는 법, NOT_A_FEATURE 폴더 처리를 적고,
보안·계약 변경 표와 알려진 제한을 적었다. 절의 해시는 모두 이 브랜치
조상이다(git merge-base --is-ancestor로 확인).
위험: 두 다운스트림에 시험 병합을 하지 않아 충돌 수를 모른다.
검증: tests/unit/changelog-review-ids.test.ts 통과(desktop test:unit).
config/scale/feature-shape-growth.json은 참조 기능 사본으로 잰 값이고,
기준 근거(feature-shape-ceilings.json의 axes)도 그 수치를 쓴다. 앞
커밋들이 측정 대상을 생성 기능으로 바꾸고 샘플을 지웠다.
샘플을 지운 트리(8c4b09b7, 수정 파일 없음)에서 node
scripts/scale/measure-feature-shape-growth.ts --sizes=0,25,100
--repeats=2 --write로 다시 쟀다. 기능당 tsc instantiation 약 10.1만,
tsc 메모리 약 31MB, 지연 JS 약 6.7KB와 9파일, 라우트 3개다. axes의
문장을 이 값과 firstFeatureGzipBytes에 맞췄다. 기준선 시험이 측정
대상(sourceFeature)도 본다.
위험: 시간 값은 desktop(i5-10400F, 부하 기록 포함)의 것이다. 400개 이상은
재지 않았다(D-18 선택).
검증(desktop): 같은 크기의 두 반복에서 컴파일러 수치가 같다.
tests/unit/feature-shape-growth.test.ts 통과.
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로
템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다.
참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록
7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트
참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은
비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을
하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다.
기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로
옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플
경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다.
레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약
기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능
539B, context 4B)을 다시 받았다.
위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은
수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에
공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는
플랫폼 코드에 남았다.
검증(desktop): check:types, lint, check:architecture, check:registries,
check:ci, verify:documentation, test:unit, test:component,
test:contract, test:integration, test:recipes, test:coverage(Risk
coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual,
test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76
checks), test:sample-removal SKIP, build, check:bundle.
규모 측정(S4 3.1절 S-6)은 참조 기능을 복사해 이름을 바꿔 잰다.
create:feature의 planFeature로 사본마다 --with-create --keyed 기능
파일을 만든다(자기 계약 패키지와 topic, context당 200개). 초기 JS
기록에 firstFeatureGzipBytes를 더하고, context 비용은 둘째 기능을 새
context에 둘 때와 같은 context에 둘 때의 차이로 잰다. 옛 정의는 기능이
없는 템플릿에서 첫 기능의 공용 코드까지 context 비용으로 세어 5,788B로
상한 512B를 넘었다. 몇 바이트짜리 비용에는 기록 허용치 하한 16B를
둔다(빌드 ID에 따라 gzip이 1~2B 흔들린다). 이 트리(샘플이 아직 있는
상태)의 기록: 204,266B, 27파일, 첫 기능 797B, 기능 521B, context 12B.
위험: 성장 기준선(0·25·100개)은 샘플을 지운 트리에서 뒤 커밋이 다시
잰다. 이 커밋의 기준선 파일은 아직 참조 사본으로 잰 값이다.
검증(desktop): feature-shape-growth 등 4파일 57 passed, test:unit 통과.
참조 기능 e2e 3개가 "기능 하나가 실제 브라우저에서 라우트·폼·
저장까지 된다"를 맡는다. 청크 복구, 부트 실패, preload 시험도 설치된
기능에 기댄다.
S4 9.1절 (가)대로 한다. scripts/lib/generated-feature.ts가 저장소
사본에 create:feature order-feature --with-create --keyed를 만들고,
spec은 그 사본의 빌드를 띄워 돈다. 참조 e2e의 검사(로그인, 목록, 폼
검증·이탈 확인·320px, en-US, 저장과 멱등 키, 429 뒤 다시 시도, 결과
불명과 같은 키 재전송, 키보드 포커스, 상태별 axe)를 생성 기능에
옮겼다. 오래된 탭의 청크 복구는 생성 기능 목록 라우트를, 부트 실패는
생성 기능을 넣은 사본을, preload 시험은 생성 기능 실행부 청크를 쓴다.
위험: 생성 기능의 동작만 본다. 제품 기능은 자기 spec이 필요하다.
사본 빌드가 spec과 브라우저마다 돈다(빌드 1초 안팎).
검증(desktop): 샘플을 지운 최종 트리에서 test:e2e 183 passed,
test:a11y 통과.
매뉴얼 예제 칸 14곳(S4 3.3절)과 산문 30여 곳이 참조 기능을
가리킨다. problem details(Envelope가 아닌 백엔드) 응답 매핑의 예는
참조 기능에만 있다.
생성기 출력이 그 모양을 만들면 그 경로로 바꿨다. 없으면 매뉴얼 안
코드 조각으로 썼다: problem details의 분류와 매핑(02 결정표 4절,
소유자 결정 D1), 도메인 모델, 검색값 스키마와 hook, 실패 행동 hook,
403 페이지 시험. 조각마다 manual-code-block 표식에 둘 경로를 적는다.
tests/unit/manual-code-blocks.test.ts가 저장소 사본에 create:feature
invoice-feature --with-create를 만들고 조각을 그 경로에 그대로 넣어
tsc(app, test), eslint, check:architecture, 그 기능 폴더의 vitest를
돈다. 조각의 동작은 tests/fixtures/manual-code-blocks/가 본다.
위험: 403 조각은 본문 없는 403으로 답한다. 공유 시나리오
forbidden-403(JSON 본문)은 jsdom + MSW에서 실행기의 본문 cancel이
끝나지 않아 화면이 로딩에 머물렀다. 실행기는 고치지 않았다. 사본에
이미 invoice-feature가 있는 프로젝트에서는 이 시험이 생성 단계에서
실패한다.
검증(desktop): test:unit 213 files 3096 passed(이 커밋까지),
verify:documentation PASS_SCOPED, lint 통과.
src/features/local-draft-feature는 기능이 아니라 IndexedDB recipe의
소비자다. 시험 5개와 recipe가 쓰고, 그래서 생성기에 NOT_A_FEATURE
예외가 있었다(S4 3.1절 S-3).
코드를 tests/fixtures/indexeddb-consumer/로 옮기고 import만 고쳤다.
NOT_A_FEATURE 표식은 이 폴더만 썼고 다운스트림 둘에도 없어 생성기에서
지웠다. 선언 없는 폴더는 밖으로 옮기라는 메시지로 실패한다. 매뉴얼
오류표, README, starter-experience, capability-consumer-experience,
patterns를 고쳤다.
위험: fixture는 기능 폴더 밖이라 기능 계층 규칙(dependency-cruiser)이
걸리지 않는다. recipe가 tests/ 아래 파일을 type import한다.
검증(desktop): test:contract, test:recipes, test:browser-capabilities,
test:unit 통과.
셸 동작을 보는 e2e(반응형, 스크롤 복원, 해시 링크, 타이포그래피,
건너뛰기 링크, 메뉴 이동, 운영 CSP, compact, en-US의 lang)가 지울 예제
화면을 열거나 그 메뉴를 누른다.
홈과 /examples/platform으로 옮겼다. 스크롤 복원은 계약 표가 그려진 뒤
스크롤하고, 해시 링크는 비동기 표보다 위에 있는 첫 절을 대상으로
한다. WebKit은 scroll anchoring이 없어 표 아래 대상이 1px 밀렸다.
갤러리 자체의 320px 리플로는 앞 커밋의 workshop 시험이 맡는다.
위험: 홈과 플랫폼 개요의 모양이 바뀌면 이 시험들의 대상도 바뀐다.
검증(desktop): 샘플을 지운 최종 트리에서 test:e2e 183 passed.