소유자가 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절
매뉴얼 예제 칸 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 통과.
문제
1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조
기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다.
검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation-
readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조
기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도
실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가
예제 경로에서 거짓이다.
고른 방법
- 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로,
README, starter-experience, static-delivery, compatibility,
backend-api-and-server-state-contract, manual-checklist,
adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의
참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로
적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다.
1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을
지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과
measure 명령 세 줄도 같은 규칙으로 고쳤다.
- patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS
안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈
위치로 고쳤다.
- 테스트: template-feature-removal-documents.test.ts에 "names their paths
and scripts only where verify:documentation checks them"을 더했다. 검사기가
읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿
기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다.
같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞
커밋의 "passes in a copy without reference-feature"가 본다.
- 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책).
검사기와 같은 규칙을 두 곳에 두게 된다.
위험·한계
- 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다.
백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다.
- 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이
아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/template-feature-removal-documents.test.ts
tests/unit/documentation-readiness.test.ts, corepack pnpm
verify:documentation, corepack pnpm test:sample-removal
Refs: 1105/14-03
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 둘.
- 1105/12-04(실행 격리 브랜치)는 `vite.config.ts`가
`scripts/lib/run-isolation.ts`를 가져오게 해, 저장소를 임시 루트에 복사해
빌드하는 두 목록(`scripts/scale/measure-feature-shape-growth.ts`,
`tests/unit/product-feature-selection-build.test.ts`)에 그 파일을 더했다.
1105/15-03(이 브랜치)은 두 목록을 `scripts/lib/vite-build-inputs.ts` 하나로
옮겼다. 두 파일의 충돌은 15-03 쪽으로 풀고, 옮긴 목록에
`scripts/lib/run-isolation.ts`를 더한다. 더하지 않으면
`tests/unit/vite-build-inputs.test.ts`가 그 파일 이름을 대며 실패하고,
임시 루트 빌드 두 곳이 "Could not resolve './scripts/lib/run-isolation.ts'"로
실패한다.
- `scripts/lib/removal-fixture.ts`의 문서 테스트 목록에 03-01(HTTP 판정
브랜치)과 16-01(이 브랜치)이 각자 한 줄씩 더했다. 두 줄을 모두 둔다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/vite-build-inputs.test.ts tests/unit/feature-shape-growth.test.ts tests/unit/product-feature-selection-build.test.ts
Refs: 1105/12-04, 1105/15-03, 1105/03-01, 1105/16-01
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 하나.
- 1105/03-02(HTTP 판정 브랜치)가 §4의 503 `RATE_LIMIT_UNAVAILABLE`·
`RATE_LIMIT_INCOMPATIBLE`을 답 표(`backend-idempotency-answers.json`)에
옮겼다. 1105/07-01(이 브랜치)은 같은 두 code를 pin의 `notCopied`에
두었다. 합친 트리에서 `backend-contract-pin.test.ts`의 "copies the
answers from the backend table rows at the pin"이 "is both copied and
listed in notCopied"로 실패한다.
- pin의 `notCopied`를 비우고, 계약 문서 4.1절의 "지금은 §4의 `RATE_LIMIT_*`
둘"과 "§4 행은 `REQUEST_TIMEOUT` 하나"를 답 표에 맞게 고친다.
- `docs/manual/01-add-a-feature.md` 충돌은 앞 통합(1a4a220c)과 같게
푼다: "5xx 여섯" 줄과 pin·사본·drift 명령 세 줄을 함께 둔다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts
Refs: 1105/03-02, 1105/07-01
문제: 기능 하나를 더하면 템플릿 추적 파일 두 개가 바뀐다.
create:feature가 public/release-manifest.json(dev server manifest)의
setDigest·packages를 다시 쓰고, 참조 기능이 있는 동안은 초기 JS 기록
(config/scale/feature-shape-ceilings.json initialJavascript)을 명령으로 다시
써야 한다. 03 문서 A절은 "생성 명령이 쓰는 폴더 밖 파일은 둘"(context 선언,
a11y 기록)이라고만 적고, 정본 표(starter-experience.md "Adding a feature")에도
두 파일이 없다. 기능 브랜치 둘은 같은 setDigest 줄을 다른 값으로 바꿔
충돌하는데, 어떻게 푸는지는 test:unit 실패 문구에만 있다.
고른 방법(리뷰 대안 (a)): 문서와 생성 출력에 두 파일, 쓰는 주체, 다시 쓰는
명령, 충돌 처리("아무 쪽이나 고르고 명령을 다시 돌린다")를 적는다.
- scripts/create-feature.ts에 FEATURE_TRACKED_FILE_REWRITES(경로·명령)를
두고 생성 출력이 충돌 처리 줄에 쓴다.
- 03 A절에 표와 충돌 단락, "기능을 지울 때"에 초기 JS 기록 재작성, 정본 표에
두 행, 01 1단계 흐름에 manifest 재작성 줄을 더했다.
- 새 단위 테스트가 그 상수의 파일·명령이 03 A절과 정본 표에 있는지 본다.
초기 JS 기록과 그 측정 스크립트 경로는 참조 기능과 함께 지워지므로 문서에서
백틱 없이 적었다(performance-evidence.md와 같은 규칙, 제거 드릴의
verify:documentation).
버린 대안(이번에 하지 않음, 결정 대기):
- (b) dev manifest를 생성 파일로 두고(.gitignore) dev·Playwright 시작 전에
만들기: 커밋 줄이 사라지지만 dev 스크립트와 Playwright webServer 명령을
바꿔야 한다. Playwright 설정은 다른 작업(12-04)이 고치는 중이다.
- (d) 초기 JS 기록이 템플릿 자신의 값만 담게 측정에서 설치된 제품 기능을
빼기: 측정 스크립트가 어떤 기능이 템플릿 것인지 알아야 한다.
위험·한계: 충돌 자체는 남는다. 두 기능 브랜치를 합칠 때 사람이 명령을 다시
돌려야 한다. 완료 기준의 둘째 길("03 A절·정본 표가 두 파일과 충돌 처리
명령을 적는다")만 채운다. 실제 두 브랜치 git merge로 재현하지 않았다.
테스트는 문서를 읽으므로, 문서를 복사하지 않는 기능 제거 드릴에서는 돌지
않는다(`scripts/lib/removal-fixture.ts`의 문서 테스트 목록).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/feature-tracked-files.test.ts
corepack pnpm verify:documentation
corepack pnpm test:realtime-removal
Refs: 1105/16-01
문제: SW를 켜는 선택은 제품 소유 `product-capabilities.ts`로 옮겼다
(1103/09-05 일부). 그런데 저장하지 않은 편집이 있는 탭의 활성화 거절
(`blockers`)과 page controller 관측(`observe`)은 템플릿 소유
`src/bootstrap/create-runtime-composition.ts`를 고쳐야 이어진다(매뉴얼 03
"SW 켜기", 레시피 "Service Worker를 켤 때 확인할 것" 2·3). 그 파일을 고친
제품은 템플릿 동기화마다 충돌한다.
고른 방법: 기존 제품 확장 지점에 선택 칸 하나를 더한다.
`ProductComposition.serviceWorker?: { blockers?, observe? }`
(`product-composition-contract.ts`). `createRuntimeAdapters`가 `composeProduct`
결과의 이 칸을 bundle에 `productServiceWorker`로 싣고, 템플릿 조립
(`create-runtime-composition.ts`)이 telemetry와 같은 방식으로 받아
`createOptionalRuntimeHost`에 넘긴다. blockers 목록은 한 번 복사한다. 던지는
blocker는 page controller가 이미 막는 쪽으로 본다. page controller는
`observe`의 throw를 잡지 않으므로, 제품 sink가 던져도 worker 흐름이 바뀌지
않게 조립에서 감쌌다. 매뉴얼 03과 레시피 2·3을 새 자리로 고쳤다.
버린 대안:
- `product-composition.ts`에 새 export(`composeProductServiceWorker`)를 요구.
이미 그 파일을 가진 다운스트림이 동기화하면 import가 깨진다. 선택 칸은
기존 `composeProduct`를 그대로 둔다.
- `composeProduct`를 조립에서 한 번 더 부르기. capability와 credential이 두
벌 생긴다.
위험·한계: 일부만 닫는다. 남은 것:
- 활성화 화면(`onUpdateWaiting`·`requestActivation()`)과 reload 안내를 이을
제품 소유 자리가 없다(레시피 4·5, 0925/06-05).
- realtime·Web Worker·오프라인 명령은 여전히 조립이 거절한다
(`optional-runtime-host.ts`, 그 런타임이 템플릿에 없다).
`product-composition.ts`(제품 소유, 출하 상태 빈 값)는 고치지 않았다. 칸이
선택이라 기존 제품 파일과 1105/09-01의 타입 검사 탐침 내용이 그대로
통과한다.
검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/component/runtime-composition-service-worker-product-wiring.test.ts tests/component/runtime-composition-service-worker-telemetry.test.ts
- RED: "passes the product's blockers and observer to the page controller"가
옛 조립에서 observe 기록이 비어 실패한다.
- 함께: check:types, lint, check:architecture, verify:documentation
Refs: 1103/09-05
문제: 1103/02-01이 제품 closer를 scope reset에 넣었다. template
participant 하나가 제품 closer를 차례로 부르고, 하나라도 던지면 이유 없는
Error를 던진다. scope runtime은 그 실패를 `failed = true`로만 받아 scope를
`FAILED`에 둔다. 그동안 모든 서버 요청이 `SCOPE_FENCED`로 막히는데 진단
기록은 0건이다(리뷰 실험 E-3). 계약의 `ProductScopeParticipant.label`을
읽는 코드도 없다. 개발자는 "로그아웃 뒤 앱이 요청을 안 보낸다"만 보고 원인
closer를 찾으려면 closer를 하나씩 지워 봐야 한다.
고른 방법(리뷰 대안 (다)):
- scope runtime이 reset의 실패 단계마다 `cache.operation.failed`를 하나
남긴다. `operation: "SCOPE_RESET"`, `reason`은 `PARTICIPANT_FAILED`·
`CACHE_RESET_FAILED`·`GENERATION_ACTIVATION_FAILED`(+ 목록 함수가 던질
때 `PARTICIPANTS_UNREADABLE`), `error_kind`, participant 실패면
`scope_participant: <label>`. template participant 실패도 같은 길로
남는다.
- 진단 계약에 `scope_participant` 키를 더한다(cardinality `topology`,
값 정책 `isScopeParticipantLabel` = 소문자 kebab-case 48자 이하). label은
제품 코드가 고른 문자열이라 projection이 받는 닫힌 토큰으로 제한했다.
- 제품 closer를 wrapper 하나로 감싸지 않고 각자 order 10 participant로
넘긴다. 그래서 `participants`가 reset마다 읽는 함수도 받는다
(`ServerStateScopeDependencies`, 배열은 그대로 받는다). 순서와 "하나가
실패해도 나머지를 부른다"는 그대로다.
- 조립은 형식에 맞지 않는 제품 label을 `TypeError`로 거절한다. 부팅에서
바로 드러나야 진단에서 label이 빠지는 일이 없다.
버린 대안:
- (가) 문서에 "closer는 던지지 않게 쓴다"만 적기: 결함이 그대로다.
- (나) wrapper만 제품 label을 기록: template participant 실패는 계속
조용하고, 한 실패가 wrapper와 runtime에서 두 번 기록된다.
- label을 `operation`이나 `reason` 값에 섞기: 계약 변경은 없지만 그 키의
뜻이 흐려진다.
위험·한계:
- 진단 계약(`src/contracts/diagnostics.ts`)에 키 하나, 함수 하나가 더해진다.
더하기만 해서 호환은 깨지지 않는다. CHANGELOG [계약] 행이 필요하다.
- 제품 label 형식이 좁아졌다. `Browser Files` 같은 label을 쓰던 제품은
부팅에서 `TypeError`가 난다. 저장소 안의 label(`browser-files`, 테스트의
label)은 모두 맞는다.
- 화면이 `FAILED`를 어떻게 보이는지는 바꾸지 않았다(영역 08·09).
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/server-state-scope-runtime.test.ts
tests/unit/runtime-adapters-product-scope-participants.test.ts
tests/unit/observability-cardinality.test.ts tests/unit/diagnostics.test.ts
- corepack pnpm check:diagnostics
- node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts
Refs: 1105/02-01
문제: 런타임 설정에 비밀처럼 보이는 키(`CLIENT_SECRET` 등)가 있으면
부팅이 CONFIG_SECRET_NAME_REJECTED로 멈추지만, 안전한 부팅 오류에는
buildId만 있고 어느 키인지가 없다. assertSafeConfigNames가 던진 오류의
message에는 키 이름이 있었지만 loadRuntimeConfig가 그 오류를 버렸다.
같은 파일의 스키마 실패는 키 이름을 invalidKeys로 싣는다.
고른 방법: assertSafeConfigNames가 UnsafeConfigNameError를 던지고 그
`key`에 거절한 키의 점 경로(`CAPABILITY_OVERRIDES.AUTH_TOKEN`,
`FEATURE_OVERRIDES.<id>.CLIENT_SECRET`)를 싣는다. 로더는 그 경로를
스키마 실패와 같은 SAFE_KEY_PATTERN으로 거른 뒤 invalidKeys에 넣는다.
오류 화면은 이미 invalidKeys를 "잘못된 설정 키"로 보인다. 값은 어디에도
싣지 않는다. 버린 대안: message에서 키를 정규식으로 다시 읽는 것.
message 문구가 바뀌면 조용히 빠진다.
위험·한계: 키 이름은 거절된 문서에서 온다. 그래서 길이·문자를 제한하고,
그 밖의 이름은 빼고 코드만 남긴다. 첫 번째로 걸린 키 하나만 싣는다
(검사가 첫 키에서 멈추는 동작은 그대로). assertSafeConfigNames의
시그니처와 message는 바꾸지 않았다. UnsafeConfigNameError는
src/contracts/env.ts에 새로 더한 export다(추가만).
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/runtime-schema/runtime-config.test.ts
Refs: 1103/07-04
문제
c15345c·db5728b·0eba082의 dev 전용 Vite 미들웨어(dev server가 설치된
기능의 contract set으로 manifest를 냄)를 넣은 뒤로, dev server를 쓰는
capability e2e가 "requestfailed:GET:/release-manifest.json:net::ERR_ABORTED"로
떨어졌다. 같은 호스트에서 번갈아 쟀다: 미들웨어 있음 5/30·2/30 실패, 없음
0/30·0/30(부하가 더 높았다). trace에서는 첫 manifest 요청이 200 헤더 뒤
끊기고 65 ms 뒤 두 번째 요청이 성공한다. 원인을 끝까지 좁히지는 못했다.
감시 이벤트(파일 쓰기)를 없애도 같았다.
고른 방법
- 미들웨어를 지운다. dev server는 커밋된 public/release-manifest.json을
그대로 낸다.
- 그 파일의 contractSet을 설치된 기능으로 다시 쓰는 일을 명시적 단계로
둔다: `create:feature`가 생성 뒤 scripts/write-dev-release-manifest.ts를
돌리고, 기능 제거 드릴이 지운 뒤 돌린다. 매뉴얼의 되돌리기·기능 지우기
절과 errors.md에 같은 명령을 적었다. 레지스트리 기준선과 같은 방식이다.
- tests/unit/dev-release-manifest.test.ts가 커밋된 파일이 설치된 기능의
contract set과 같은지 보고, 다르면 다시 쓰는 명령을 말한다.
- 함께: vite.config.ts가 artifacts/·dist/·.tmp/를 감시하지 않는다.
Playwright trace의 .html이 열린 페이지를 모두 다시 불러오게 했다(dev
server 로그의 page reload).
- 버린 대안: dev 부팅에서 contract set 검사 건너뛰기. 검사하는 테스트와
같은 조건을 dev만 따로 두게 된다.
위험·한계
- 기능을 손으로 지우고 명령을 잊으면 dev server가 부팅하지 못한다.
test:unit이 그 상태를 이름과 명령으로 알린다.
검증
- test:unit 2,880건, dev-release-manifest·create-feature 테스트 45건,
check:types, lint, verify:documentation 통과.
- 생성 기능을 넣은 clone의 dev capability e2e와 merge 단계 14개는 이 커밋
뒤 깨끗한 clone에서 돈다.
Refs: docs/reviews/2026-11-03-maturity-review/README.md 14.5 14.6 X2 #3, 16-09
문제
tests/e2e/accessibility.spec.ts는 보호 라우트의 모든 API에 맨 배열
`[]`를 답했다. create:feature가 만드는 기능은 responseEnvelope:
"ENVELOPE_V1"이라 `[]`는 ENVELOPE_MISMATCH가 되고, 페이지는 경고 상자를
그린다. spec은 h1과 axe만 봐서 오류 화면을 검사하고도 통과했고, 증거는
그 라우트를 "passed"로 적었다. 경로 파라미터는 `:resourceId`만 바꿔서
다른 이름을 쓰는 기능은 이 템플릿 파일을 고쳐야 했다.
고른 방법 (결정 D4 (b))
- tests/e2e/support/installed-api-answers.ts가 요청을 설치된 GET
descriptor에서 method와 pathTemplate으로 찾는다. 출력 스키마가 빈
목록을 받으면 그 operation의 모양으로 답한다(Envelope면 MSW 시나리오와
같은 successEnvelope, 아니면 맨 배열).
- 목록만 읽은 라우트는 로딩이 끝난 뒤 경고 상자(role="alert")가 없다고
단언한다. 모양이 다시 어긋나면 axe 통과 대신 여기서 실패한다.
- 경로 파라미터는 이름과 상관없이 모두 a11y-1로 바꾼다. 기능을 더해도
spec을 고치지 않는다(16-03 앞 절반).
- 설치된 GET이 아닌 요청, 빈 목록을 받지 않는 파라미터 없는 GET은
501로 답하고 그 목록이 비어 있다고 단언한다.
- 매뉴얼 01·03, starter-experience, create-feature 참조, 수동 점검
문서의 "모든 API에 []", ".replace를 잇는다" 문장을 동작에 맞췄다.
- 버린 대안: 전역 Envelope 응답(참조 기능 DTO가 거꾸로 깨짐), 기능마다
접근성 spec 생성(파일·실행 시간 증가).
위험·한계
- 한 자원을 읽는 GET(상세 페이지)에는 빈 목록 말고 줄 본문이 없다.
그 라우트는 지금처럼 실패 상태로 검사하고 a11y-data-state
annotation만 남긴다. 경고 상자 단언은 그 라우트에서 건너뛴다.
- write-a11y-report.ts의 증거는 annotation을 읽지 않는다. 상세 라우트도
"passed"로 적힌다.
검증
- 새 unit 테스트 6건: helper가 없을 때 실패, 추가 뒤 통과.
- 템플릿 상태 chromium test:a11y 대상 spec 14건 통과.
- create:feature sample-feature 상태에서 `@a11y /sample` 세 엔진 통과.
변이 1(Envelope 대신 맨 배열): 세 엔진 모두 경고 상자 단언으로 실패.
변이 2(빈·성공 상태에서만 보이는 이름 없는 버튼): 세 엔진 모두
axe button-name으로 실패. 생성 파일은 지웠다.
- check:types:test, eslint, verify:documentation, check:ci 통과.
Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-01
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-03
문제: browser-files runtime은 세션을 모르고, 닫는 수단은
runtime.dispose() 하나다. 설계 문서는 로그아웃·계정 전환에 "server-state
scope reset participant로 dispose()를 등록하라"며 템플릿 소유 파일
runtime-adapters.ts를 가리키는데, 매뉴얼은 제품이 그 파일을 고치지
않는다고 한다(09-02). 제품 확장 지점 composeProduct는 부팅 때 한 번
불리고, context에 participant 등록도 lifecycle 구독도 없다. 그래서
연결하지 않으면 이전 사용자가 고른 File, preview blob URL, 진행 중
download가 다음 세션까지 남는다(공유 기기에서 이전 사용자 파일이
메모리와 다운로드 폴더에 남을 수 있다).
고른 방법(리뷰 5.3절 (다) + 레시피 예제):
- ProductComposition에 선택 칸 scopeParticipants(ProductScopeParticipant:
label, close)를 둔다. 템플릿은 scope reset의 §10.6 10단계(offline
lease 해제) 자리에 "product" participant 하나를 두고, composeProduct가
돌려준 것을 순서대로 부른다. 하나가 실패해도 나머지를 부르고, 실패가
있으면 template participant와 같이 READY로 가지 않는다(FAILED).
composeProduct는 scope가 생긴 뒤 불리므로(context가 fence를 쓴다) 이
자리를 미리 만들고 나중에 채운다.
- recipes/frontend-capabilities/browser-file-session-capability.ts:
기능에는 runtime 대신 current() getter를 주고, participant가 dispose한
뒤 다음 호출에서 새 runtime을 만든다. indexeddb 레시피와 같은 자리다.
- 설계 문서와 매뉴얼 03 C절이 이 방법을 가리킨다. 제거 드릴이 새
레시피 파일도 같이 지운다.
버린 대안: (가) 문서만 고침 — feature presentation은 adapter를 만들 수
없어 제품마다 factory를 다시 설계한다. (나) context에 lifecycle 구독
위임 — FENCED → participant → READY 순서와 "실패는 READY를 막는다"를
제품이 직접 지켜야 한다. (라) runtime이 세대 AbortSignal을 받음 —
adapter가 세대를 알게 되고 다른 opt-in runtime도 따로 받아야 한다.
위험·한계:
- 제품 계약 표면이 하나 는다(선택 칸이라 기존 제품 파일은 그대로
컴파일된다, [계약]).
- 기능은 current()를 작업마다 불러야 한다. 이전 세대에서 받은 runtime을
들고 있으면 UNAVAILABLE을 받는다. FENCED 동안 current()를 부르면 다음
세대 runtime이 미리 만들어진다(빈 runtime이라 이전 사용자 데이터는
없다).
- app dispose(infrastructure.dispose)는 제품 participant를 부르지 않는다.
- 실제 브라우저 2탭 로그아웃 E2E는 없다(조립된 화면이 없다).
- scripts/test-browser-file-storage-runtime-removal.ts는 02-06 담당 작업도
고칠 수 있는 파일이다. runtimePaths에 한 줄만 더했다.
검증:
- RED: tests/recipes/browser-file-session-capability.test.ts가 계정 전환
뒤에도 이전 runtime의 readRange가 ok로 실패.
- GREEN: 같은 테스트에서 계정 전환 뒤 ① 이전 runtime readRange
UNAVAILABLE ② 진행 중 bounded download ABORTED, handoff 0회 ③ 새 세대
runtime의 파일 선택 SELECTED. tests/unit/runtime-adapters-product-scope-
participants.test.ts 2건(순서, 실패 시 FAILED와 나머지 실행).
- 변이 4개(등록 누락, 실패 삼킴, 첫 실패에서 멈춤, 레시피 dispose 누락)
모두 새 테스트가 잡았다.
- runtime-adapters 관련 unit 3파일 + tests/recipes 47건 통과.
check:types, 바꾼 파일 eslint, check:architecture, verify:documentation
통과.
Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-01
문제: 배포 슬롯을 채우거나 제품 전용 merge 검사를 더하려면 템플릿 소유
config/ci/gates.json(약 3,000줄)과 생성 workflow를 고쳐야 했다. 문서도
"deployment job을 gates.json에서 고치라"고 적었다. 템플릿 gates.json이
바뀔 때마다 제품은 큰 JSON과 생성 YAML의 충돌을 손으로 풀어야 했고,
다운스트림 tech-log는 이미 제품 커밋 3개에서 gates.json을 고쳤다.
고른 방법: 제품 소유 config/ci/product-gates.json을 둔다. 템플릿은 빈
파일로 싣고 고치지 않는다. 담을 수 있는 것은 둘뿐이다.
- deployment: deploy package script와 vars.*·secrets.* 바인딩. 나머지
슬롯(promoted-release download, digest로 확인하는 extract, deploy)은
템플릿이 렌더링하고, 채운 계약을 다시 parse해 슬롯 규칙(앞 커밋)을
그대로 적용한다. secret은 deploy 단계에만 간다. gates.json과 overlay
양쪽에서 슬롯을 채우면 거절한다.
- mergeGates: PRODUCT-GATE-NNN id의 package script. 템플릿 job 뒤의
product_merge_gate job이 merge와 같은 조건에서 matrix로 돈다. FE-GATE
id·명령·산출물·readiness 공식은 건드리지 못한다.
loadCiGateContract와 생성기, check:ci가 두 파일을 함께 읽고, 계약
기준선(contract-baseline.json)은 템플릿 계약만 센다. 없는 script는
거절하고, 제품 gate script는 ungated 검사에서 gated로 센다.
버린 대안: 저장소 변수로 배포 명령만 받기(제품 게이트를 못 풀고 실행할
명령이 저장소 밖에 숨는다), 제품 전용 workflow 파일(Gitea에서 run 사이
산출물 전달이 검증되지 않았다).
위험·한계: 제품 gate는 ci:gate의 로그·증거 산출물과 readiness 공식
밖이다. merge를 막으려면 제품이 그 job을 필수 검사로 지정한다. 생성
workflow는 여전히 커밋되는 파일이라, 템플릿 변경과 같은 줄을 건드리면
재생성이 필요하다. 실제 Gitea runner에서는 돌리지 않았다.
검증: tests/unit/product-ci-overlay.test.ts 11건(빈 overlay, 슬롯
채우기와 기준선 유지, 양쪽 채우기 거절, 없는 script 거절, 제품 job
렌더링과 실행 확인, 스키마 거절 6건). 작업 트리에서 overlay와 script를
채워 generate:ci-workflow → check:ci PASS, CI workflow bytes PASS, 생성
YAML 파싱 확인 후 되돌렸다. 그 상태의 workflow와 gates.json에 템플릿
변경(게이트 이름 2개)을 diff3로 3-way 병합하면 충돌 0이다.
ci-workflow-generation 425건, check:ci PASS.
Refs: docs/reviews/2026-11-03-maturity-review/12-guardrails-ci.md 12-07
문제
Service Worker를 켜는 유일한 방법은 src/features/installed-runtime-capabilities.ts의
SERVICE_WORKER 상수를 바꾸는 것이었다. 그 파일에는 "Product-owned." 표시가
없고, 매뉴얼 03 D절은 src/features/installed-*.ts를 고치지 말라고 한다.
매뉴얼대로 하면 SW를 켤 수 없고, 켜면 동기화마다 템플릿 파일을 손으로
병합한다. 템플릿 상태 설명과 제품 선택 상수가 한 블록에 섞여 있었다(1101/09-05).
고른 방법
리뷰의 최소 방향을 따른다.
- 선택 상수 넷(REALTIME, WEB_WORKERS, SERVICE_WORKER, OFFLINE_COMMANDS)을 제품
소유 src/features/product-capabilities.ts의
PRODUCT_RUNTIME_CAPABILITY_SELECTION으로 옮긴다. 09-02에서 만든 같은 새 제품
소유 파일이다. product-contracts.ts에 넣지 않은 이유: 계약 층(src/contracts)이
아니라 기능 카탈로그 옆의 선택이고, 템플릿은 복사 뒤 기존 제품 소유 파일에
칸을 더하지 않는다.
- installed-runtime-capabilities.ts는 템플릿 소유로 남고 그 선택을 검사
(validateRealtimeContributions, validateWebWorkerContributions)하고 투영만
한다. §3.5 설명과 템플릿 상태 설명은 여기에 남는다.
- 매뉴얼 03 C절에 "SW 켜기"를 넣었다. 조립 거절 메시지, e2e SW 빌드 도우미의
편집 대상(premise 1), 레시피·운영 문서, dependency-cruiser 주석의 경로를
새 파일로 바꿨다.
- 09-02 typecheck 테스트는 이제 출하된 product-capabilities.ts에 타입만 채우고
(선택은 유지), 복사 목록은 REMOVAL_FIXTURE_COPY_TARGETS 하나를 쓴다.
위험·한계
- 리뷰가 함께 제안한 composeProduct의 SW 연결 칸(blockers, observe)은 만들지
않았다. 그 연결은 여전히 템플릿 파일 create-runtime-composition.ts를 고쳐야
한다. 매뉴얼 "SW 켜기"에 적었다.
- 템플릿 안의 선택을 이미 바꾼 다운스트림은 값을 새 파일로 옮겨야 한다.
검증
- RED: tests/unit/product-runtime-capability-selection.test.ts 3건(선택이 제품
소유 파일에만 있음, 제품 SW 선택 투영, 잘못된 선택은 여전히 검사)이 수정 전
실패.
- 그 테스트, service-worker-build-output, optional-runtime-host,
runtime-composition-service-worker-telemetry, product-features,
product-extension-typecheck, runtime-adapters 통과.
- check:types, check:architecture, eslint, verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-05
문제
제품 확장 지점이 실행 경로에서는 동작했지만 타입 검사 경로에서 막혔다.
(a) 문서대로 product-composition.ts에서 FeaturePlatformCapabilities를
보강하면 check:types:node가 실패했다. scripts 프로그램은 기능 코드를 끌어오지만
product-composition.ts는 끌어오지 않아 보강이 보이지 않았고, 오류는 기능
파일을 가리켰다. (b) 기본값 있는 제품 설정 키(.default()) 하나가 RuntimeConfig를
리터럴로 쓰는 템플릿 테스트 7개 파일의 타입을 깼다. 픽스처는 vi.mock이라 이
경로를 지나지 않았다.
고른 방법
- 제품 소유 빈 파일 src/features/product-capabilities.ts를 두고
FeaturePlatformCapabilities가 그 ProductFeaturePlatformCapabilities를
extends한다. feature-adapter-contribution.ts가 import하므로 기능을 보는 모든
프로그램에 들어간다. 문서만 "기능 파일 안에서 보강"으로 고치는 최소안은
capability 하나를 여러 기능이 쓸 때 보강 위치가 갈려 버렸다. 기존 제품 소유
파일에 칸을 더하지 않고 새 파일로 둔 이유: 템플릿은 복사 뒤 제품 소유 파일을
고치지 않으므로, 새 파일이어야 동기화 때 충돌 없이 들어간다.
- tests/helpers/runtime-config.ts의 testRuntimeConfig: 템플릿 키는 테스트가
쓰고, 제품 키는 실제 스키마(validateRuntimeConfig)로 기본값을 채운다. 템플릿
테스트 6개 파일이 이것을 쓰고, release-coherence는 문서 타입을 z.input으로
바꿨다. 제품 키를 모두 Partial로 하는 대안은 기본값 키에도 undefined 처리를
강요해 버렸다.
- tests/unit/product-extension-typecheck.test.ts: 복사본에 제품 소유 파일 세 개와
기능 하나를 실제 파일로 채우고 tsc app·node·test를 돈다.
- 문서: starter-experience 표, 매뉴얼 01·03·patterns·create-feature,
frontend-application-foundation, 계약 주석.
위험·한계
- 기본값 없는 필수 제품 키는 여전히 템플릿 테스트에서 실패한다(이제 타입이
아니라 helper가 이유를 적고 throw). 문서에 ".default() 또는 .optional()"을
적었다.
- product-composition.ts 안에서 이미 보강한 다운스트림은 보강을 새 파일로
옮겨야 node 검사가 통과한다.
검증
- RED: 새 typecheck 테스트가 수정 전 app·node(보강 미연결)와 test(템플릿
테스트 8건, E-PROD와 같은 위치)에서 실패.
- 수정 후 그 테스트와 영향받는 9개 테스트 파일 → 10 files / 83 tests 통과.
- check:types(tsc app·node·test), check:architecture, eslint,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02
문제
짝 백엔드의 실시간 출구는 STOMP-over-SockJS 채널(/ws, /topic 구독 1개,
Map<String,String> 투영, 재전송 없음)과 raw WebSocket 라이브러리 API,
NDJSON·JSON text sequence writer다. 프론트 SSE 어댑터는
text/event-stream과 REALTIME_EVENT_V1 envelope을, WebSocket 어댑터는
subprotocol "realtime.v1"을 요구한다. 어느 repo에도 이 불일치와 지금
되는 경로가 적혀 있지 않아, 채택자가 두 repo를 다 읽어야 안다.
고른 방법
- 리뷰의 최소 방향을 프론트 repo 안에서 따른다. 설계 문서에 0.1절을
두고 transport별 대응표(지금 연결되나·이유), push가 필요할 때의 세
길, 재검토 조건을 적는다. 레시피 Realtime 절과 매뉴얼 03 C절에서 한
줄로 링크한다.
- 다시 확인한 백엔드 사실(읽기만): 아키텍처 테스트가 MVC SseEmitter를
금지한다(ForbiddenApiArchitectureTest NO_SSE_EMITTER, 결정 D3).
StreamMediaType.SSE는 OpenAPI 생성기만 쓴다. subprotocol 협상 코드는
없다. 그래서 첫째 길을 SSE가 아니라 realtime.v1 WebSocket handler로
적었다.
- 지금 되는 경로(bounded polling)는 사실로 적고, push 경로는 고르지
않았다. 제품 결정이다.
- 버린 대안: desktop-server-git/design-docs/에 쓰기. 이 브랜치 밖이라
함께 합쳐지지 않는다. 필요하면 그쪽에서 이 절을 링크한다.
위험·한계
- 백엔드 사실은 지금 백엔드 HEAD(70fb80bf)를 읽은 것이다. 백엔드가
바뀌면 표가 낡는다. 재검토 조건에 적었다.
- 실제 연결은 실행하지 않았다(리뷰와 같음).
검증
- verify:documentation PASS_SCOPED. documentation-readiness·
changelog-review-ids 테스트 15건 통과.
Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-02
문제
설정 키 금지 조각 검사(assertSafeConfigNames: TOKEN, COOKIE, SECRET 등)는
부팅 때 한 곳에서만 돈다. ece944d가 연 제품 키 경로로 PRODUCT_COOKIE_NOTICE
같은 키를 zod 필드·FE-REG-ENV 행·config/runtime 값으로 더하면
generateRuntimeConfig, 범위 테스트, check:registries가 모두 통과한다. 그
config.json으로 배포하면 모든 사용자가 부팅 실패 화면을 보고, 오류 코드
CONFIG_SECRET_NAME_REJECTED에는 키 이름이 없다(실험 E-4).
고른 방법
env-registry-coverage에 사례 하나를 더한다. V2 스키마가 읽는 키와
FE-REG-ENV 런타임 행 키 전부로, 값은 스키마 기본값(CAPABILITY_OVERRIDES의
중첩 키 포함)으로 문서를 만들어 assertSafeConfigNames에 넣는다. 실패
메시지가 키 이름을 말한다. 규칙은 매뉴얼 03 C절의 product-contracts.ts
항목에 적었다.
버린 대안
- product-contracts.ts 주석에 규칙 적기: 이 파일은 제품 소유이고 템플릿이
복사 뒤에 고치지 않는다고 약속한 파일이다. 동기화 때 충돌을 만든다.
- generate-runtime-config에서도 검사: 스키마가 strict라 제품 키는 스키마
필드여야 들어가고, 그 키는 이 테스트가 먼저 잡는다. 같은 검사를 한 곳
더 두지 않았다.
위험·한계
- 부팅 오류 CONFIG_SECRET_NAME_REJECTED에 거절한 키 이름을 싣는 것은 하지
않았다(src/bootstrap/load-runtime-config.ts, 다른 작업 범위).
- 제품 record 필드의 임의 중첩 키(값으로만 생기는 키)는 기본값에 없으면
이 테스트가 보지 못한다. 부팅 검사가 여전히 막는다.
검증
- E-4 재실행: PRODUCT_COOKIE_NOTICE를 제품 zod 필드와 행으로 더하면 이
사례가 "Forbidden client configuration key: PRODUCT_COOKIE_NOTICE"로
실패한다. 되돌리면 4건 통과.
- eslint, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-04
문제: docs/manual(7c7ef32)만 보고 notice-feature(목록·상세·작성, GET 2 +
KEYED POST 1)를 만든 실험(b58d131, 합치지 않음)에서 매뉴얼이 답하지 않아
코드를 읽어야 했던 곳이 나왔다.
| 막힘 | 절 | 매뉴얼에 없던 것 |
|---|---|---|
| 1 | 01-3단계 | 백엔드 Envelope와 뼈대 problem details 중 무엇을 따르나 |
| 2 | 01-3단계 | V2 입력 칸(requestSource, pathSchema, pathParameterNames, maxEncodedSearchBytes, boundary) |
| 3 | 01-5단계 | routeId가 무엇에 쓰이고 쓰기에는 어느 route를 적나 |
| 4 | 01-6단계 | 상세 경로를 items/ 아래 두는 이유, a11y spec 치환 고치는 법 |
| 5 | 01-10단계 | 같은 멱등 키 재전송과 요청 본문을 테스트에서 보는 법 |
| 덧 | 02-4절, 01-2단계, patterns | 503 IDEMPOTENCY_UNAVAILABLE 판정, 길이 제한 위치, 검색 폼 예 |
고친 절과 근거(코드 위치):
- 01-3단계 "응답 모양": 뼈대·MSW·V3 실행기는 DTO와 problem details를 쓴다.
V3는 본문을 벗기지 않고 검증한다(src/adapters/http/http-execution-v3.ts:1410,
1633-1647; src/adapters/http/index.ts:41-48; backend-api-and-server-state-
contract.md:161-173). MSW는 {data} 감싼 응답을 실패 시나리오로 둔다
(tests/mocks/handlers/http-scenarios.ts:80-81, 143-150). 뼈대 problem 스키마는
최상위 code다(scripts/create-feature.ts:542-550). 짝 백엔드는 모든 JSON을
Envelope로 보낸다(backend docs/web/http-contract.md:16-33).
- 01-3단계 "V2 행의 입력 칸": 칸 표와 공지 예 두 행. 근거
src/contracts/api-operations.ts:9,25-27,112-125,142-190,
src/contracts/schema-registry.ts:6-11, config/contracts/registry-governance.json:220
(boundary는 허용값만 검사), tests/unit/http-operation-v2-v3-parity.test.ts:39-49,91,
src/adapters/http/request-builder.ts:129-135(V2만 읽음),
src/contracts/external-contract-runtime.ts:33,
src/adapters/http/http-contract-bridge.ts:225-231(V3 고정 상한 8,192).
- 01-5단계 routeId: 실행기에 넘겨 관측 기록의 route_id로만 쓴다
(src/adapters/http/feature-http-binding.ts:272-273,
src/adapters/http/http-execution-v3.ts:248-254,653-655,
src/bootstrap/runtime-adapters.ts:249-293). 기준은 "요청을 보내는 화면".
참조 기능 생성은 LIST를 적었다(reference-http-gateway.ts:32-34).
- 01-6단계: items/ 이유(reference-feature-contract.ts:36-37, React Router
정적 우선), a11y spec 치환 줄(tests/e2e/accessibility.spec.ts:26-29,36-43),
파라미터 해석 실패 시 잘못된 경로 화면(src/presentation/routes/app-router.tsx:371).
드릴 잔여물 검사는 기능 ID·폴더 이름만 찾는다(scripts/test-sample-removal.ts:
114-117,383-392). URL 함수가 codec을 넘겨야 한다는 줄도 더했다
(src/presentation/routes/route-codecs.ts:36,69-87; 생성 판
scripts/create-feature.ts:934-938은 넘기지 않음).
- 03 "기능을 지울 때"·C절, 01-11단계: a11y spec 치환 줄을 손으로 지운다.
- 01-10단계, patterns "테스트": msw request:start로 요청을 모으는 예
(실험 tests/features/notice-feature/notice-pages.test.tsx, msw 2.15
node_modules/msw/lib/core/experimental/frames/http-frame.d.ts:58,
생성 판 setupServer scripts/create-feature.ts:1147-1149).
- 02-4절 503: V3는 problem 스키마 실패면 쓰기를 MAYBE_APPLIED로 두고
(http-execution-v3.ts:1633-1647), 통과하면 기능 classifyProblem이 정한다
(src/adapters/http/http-effect-certainty.ts:99-131; 참조 기능
reference-feature-contract-contribution.ts:49-70은 503을 MAYBE_APPLIED).
V2 IDEMPOTENCY_REFUSALS에 503이 없어 effect가 비고
(src/adapters/http/client.ts:1035-1038,1109-1135) 조정자가 MAYBE_APPLIED로
본다(src/presentation/adapters/query/application-query.ts:824-834). 재전송은
같은 키, 새 저장은 새 키(같은 파일 583-589, 636-669). 판정: 백엔드 행동
(http-contract.md:94 "같은 키로 나중에 다시")과 맞는다. 화면 문구만 다르다.
- 01-2단계: 길이 제한은 경계 검증. 참조 기능도 스키마·폼에만 둔다
(reference-schemas.ts:66, reference-resource-form.ts:9).
- patterns "URL 검색값을 바꾸는 폼": 짧은 예(SearchField, CollectionPage
toolbar, buildRouteUrl search).
- errors.md: V2 입력 칸 실패 메시지 3개와 Unregistered route codec.
남긴 것:
- 응답 모양 제한: 지금 생성한 기능은 짝 백엔드의 Envelope 응답을 읽지
못한다. 매뉴얼에는 제한과 선택지 둘(백엔드가 DTO를 보냄 / 프론트 V3가
Envelope를 벗김)만 적었다. 결정은 없다. CHANGELOG·리뷰 기록은 이 커밋
범위 밖이다.
- 경로 파라미터와 본문을 함께 받는 operation(PUT 등)의 V2/V3 일치 규칙이
없다는 사실만 적었다.
- 예시 코드는 실험 브랜치의 notice 기능에서 옮겼다. 이 저장소에서 다시
돌려 보지 않았다(실험 커밋 기록상 기능 테스트 21개 통과).
검증:
- node scripts/generate-product-feature-index.ts &&
node scripts/verify-documentation-readiness.ts: PASS_SCOPED,
documentReferences의 docs/manual 8개 파일 missing 0
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
tests/unit/documentation-readiness.test.ts: 2 파일 16개 통과
- 새로 적은 실패 메시지·식별자: src·scripts·tests에서 모두 찾음.
request:start는 msw 타입에서 확인
문제
- 새 기능을 추가하는 절차가 starter-experience.md의 영어 단계 7개와
폴더 밖 파일 표뿐이다. 무엇을 고르는지(context, 계약 출처, 재시도 의미,
결과 불명, 인증, 페이지 템플릿), 어느 검사가 무엇을 못 잡는지, 실패
메시지가 어느 파일을 가리키는지는 리뷰 문서(16 영역 8절)에만 있다.
리뷰 문서는 복사한 프로젝트가 지울 수 있는 작업 이력이다.
- create:feature(U7)가 생겼지만 그 인자, 만드는 파일, 사람이 해야 하는 일
(a11y 서명, 자리표시자 계약 신원 교체)을 설명하는 문서가 없다.
고른 방법
- docs/manual/을 한국어로 쓴다(결정 5). README(독자, 읽는 순서, 두는 것과
안 두는 것), 01 작업 순서 0~11단계, 02 결정표 6개, 03 기능 폴더 밖 파일,
reference/ 4개(create-feature, global-ids, patterns, errors).
- 01은 1단계에서 create:feature로 시작하는 길을 기본으로 두고, 단계마다
정할 것, 기준, 잡는 검사(명령·게이트 ID·메시지)와 못 잡는 것, 쓸 스킬을
적는다. 리뷰 시점의 "못 잡음"은 지금 코드로 다시 확인해 고쳤다(예: 루트
밖 라우트는 이제 앱 모듈이 적재 때 거부한다).
- 실패 메시지는 src·scripts의 문자열을 그대로 옮기고 값 자리만 <...>로
바꿨다.
- 목록 대신 정본 위치를 적는다(공통 원칙 8). route ID는 ROUTE_REGISTRY,
게이트는 config/ci/gates.json, 백엔드 멱등성 응답은 백엔드 템플릿
docs/web/http-contract.md §2를 가리키고 표를 옮기지 않는다. 공통 원칙은
design-docs의 conventions/feature-design-principles.md를 번호로만
가리킨다.
- 03은 starter-experience.md의 폴더 밖 표를 정본으로 링크하고 복사하지
않는다. 생성 명령이 하는 것 / 사람이 꼭 하는 것 / 조건부 / 고치지 않는
것으로 나누고, 표에 없는 절차(a11y 서명, 자리표시자 교체, 기능 삭제)만
더한다.
- 16 영역 8.4의 금지 목록(목표 디렉터리 구조 절, 예전 폴더 밖 표, 참조
페이지의 경로 문자열)은 링크하지 않고 README에 그 이유를 적는다.
- 버린 대안: 리뷰 8절을 그대로 옮기기(리뷰 시점 사실이 지금 코드와 다르고
지울 수 있는 이력에 기댄다), starter-experience.md에 한국어 절을 더하기
(입구 문서는 영어이고 다른 에이전트 소유다), 실패 메시지를 요약해 쓰기
(메시지로 문서를 검색할 수 없다).
위험·한계
- docs/README.md §1 링크는 넣지 않았다(오케스트레이터 몫). 링크하기 전에는
verify:documentation이 이 폴더를 검사하지 않는다. 폴더 링크는 바로 아래
.md만 검사하므로 reference/도 따로 링크해야 한다.
- 플랫폼 규칙 근거는 다른 에이전트가 옮기는 scale-architecture.md를 절
번호로 가리킨다. 이 커밋에는 그 파일이 없어 링크 대신 백틱 이름으로 썼다.
- 매뉴얼로 막을 수 없는 것이 남는다. 기능 전용 e2e spec은 tests/e2e에만
둘 수 있어 기능 폴더 밖이다. --context reference-context는 참조 기능
테스트 하나를 깨뜨린다. 생성 드릴은 check:bundle을 돌리지 않는다.
- "실험 E를 매뉴얼만 보고 다시 하기"는 문서로만 점검했고 실제로 다시
돌리지 않았다.
검증
- docs/README.md §1에 manual/, manual/reference/ 링크를 임시로 넣고
node scripts/verify-documentation-readiness.ts: PASS_SCOPED. 7개 문서
모두 missingPaths·missingScripts·unknownGateIds 0. 임시 링크는 되돌렸다.
- 변이: patterns.md에 없는 경로·script·게이트 ID를 넣으면 세 항목을 모두
말하며 FAIL_UNVERIFIED.
- 메시지 대조 스크립트: 백틱 안 148개 문구 중 106개는 코드에 그대로 있고,
42개는 코드가 조각을 이어 만드는 문구(접두어·필드 이름·값 채움)라 하나씩
코드에서 확인했다.
- node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts
tests/unit/deletable-history-documents.test.ts
tests/unit/repository-file-inventory.test.ts: 3파일 38건 통과.