루트 항목 하나를 옮기려면 코드 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절
62 KiB
01. 새 기능 추가하기 — 0~11단계
핵심은 둘이다.
- 뼈대는 손으로 만들지 않는다.
corepack pnpm create:feature <id>로 만든다. - 뼈대를 실제 기능으로 바꾸는 순서가 아래 0~11단계다.
다른 기능 폴더를 복사해 이름을 바꾸는 방법은 쓰지 않는다.
그 방법은 접두어 없는 전역 ID, 복사된 계약 출처, 기능 밖 테스트 의존 때문에 여러 번 막힌다.
생성 명령은 이 문제를 미리 피한 파일을 쓴다.
템플릿에는 복사해 볼 기능 샘플이 없다. 생성 뼈대에 없는 모양은 이 매뉴얼 안의 코드 조각으로 보인다.
코드 조각 위의 manual-code-block 표식이 그 조각을 둘 자리다. 조각은 create:feature invoice-feature --with-create로 만든 기능을 기준으로 쓴다.
tests/unit/manual-code-blocks.test.ts가 그 기능을 저장소 사본에 만들고 조각을 그 자리에 그대로 넣어 타입 검사와 동작 시험을 돌린다.
전체 흐름
0 경계 정하기 (기존 context? 새 context?)
→ 1 create:feature로 뼈대 만들기
→ 2 도메인 모델 (선택)
→ 3 API 계약
→ 4 application input
→ 5 HTTP 어댑터와 조립 기여
→ 6 라우트
→ 7 쿼리·뮤테이션
→ 8 페이지
→ 9 기준선과 증거
→ 10 테스트
→ 11 제거 확인
1단계의 생성 명령이 3~8단계와 10단계의 가장 작은 판을 한 번에 만든다.
- 라우트 1개 (파라미터 없는 목록)
- GET 1개 (
SAFE,EXTERNAL_BEARER). 경로는 짝 백엔드new-feature.sh와 같은/<plural>이다 - 쿼리 1개와 무효화 topic 1개
CollectionPage페이지 1개와 ko-KR·en-US 문구. 결과 수는 백엔드가 보낸meta.page.total이다- 테스트 3개와 테스트용 앱 파일 1개 (application input 단위 테스트, 라우터를 거치는 페이지 테스트, 백엔드 본문을 적은 gateway 테스트,
<base>-test-app.tsx)
--with-create를 주면 짝 백엔드 new-feature.sh가 만드는 나머지 두 엔드포인트를 함께 만든다.
- 상세 GET(
GET /<plural>/{id})과DetailPage상세 페이지 - 작성 POST(
POST /<plural>, 201)와FormPage작성 폼, 결과 불명 화면 - 작성 폼 테스트: 201 저장 뒤 상세 열기, 400
<FEATURE>_INVALID를 이름 칸에 보이고 다시 저장, 응답을 잃은 저장 - 작성은 기본이
NEVER다. 백엔드 생성기의 create가NOT_IDEMPOTENT라서다. 백엔드 create를 KEYED로 바꿨으면--keyed를 함께 준다(02 결정표 3절).
그래서 3~8단계는 "처음부터 쓰기"가 아니라 "생성된 파일을 실제 계약과 화면으로 바꾸기"다.
단계마다 적은 것
- ① 정할 것: 이 단계에서 고르는 값과 선택지.
- ② 기준: 무엇을 보고 고르나. 표가 필요한 판단은 02 결정표에 있다.
- ③ 잡는 검사 / 못 잡는 것: 실수했을 때 어느 명령(게이트 ID)이 어떤 메시지로 잡는가. "못 잡음"은 이 커밋의 검사가 잡지 못한다는 뜻이다. 메시지 전체는 reference/errors.md에 있다.
- ④ 쓸 스킬: AI 에이전트가 부를 스킬.
0단계. 경계와 소속 정하기
① 정할 것
- 기존 context에 넣을지, 새 context를 만들지.
- context: 같은 URL 앞부분(라우트 루트) 아래에서 함께 지연 로드되는 기능 묶음이다.
- 기능 ID. 케밥 표기만 쓴다. 소문자 단어를
-로 잇는 꼴이다(invoice-feature).
② 기준
- context 판단은 02 결정표 1절과 원칙 1을 본다.
- 기능 ID는 네 곳에 같은 문자열로 들어간다. 나중에 바꾸기 어렵다.
feature-module.ts의FEATURE_MODULE_ID- 계약의
featureId ApplicationFeatureInputs의 키config/runtime/<profile>.json의FEATURE_OVERRIDES키
- ID가
-feature로 끝나면 생성 명령은 그 앞부분을 접두어로 쓴다.invoice-feature면invoice,INVOICE_,Invoice다. - 근거:
scale-architecture.md§5(모듈 소유), §7(개수 예산), §9(라우터 구조).
③ 잡는 검사 / 못 잡는 것
- 기능 라우트가 context 루트 밖에 있으면 앱 모듈이 적재 때 거부한다.
- 메시지:
Route <ROUTE_ID> (<path>) of feature <id> is not under the route root of its context <context> (...) - 앱 모듈을 적재하는 테스트(라우터를 거치는 페이지 테스트, component 테스트)와 앱 부팅이 실패한다.
tests/architecture/context-route-roots.test.ts는 이 규칙을 fixture로만 고정하고, 설치된 기능의 라우트는 보지 않는다. - 생성 명령은 라우트를 늘 루트 아래에 둔다. 손으로 경로를 바꿀 때만 걸린다.
- 메시지:
- context 하나에 기능이 예산보다 많으면 생성기가 거부한다.
- 메시지:
Context <context> feature cardinality <n> exceeds budget <max> - 예산은 선언 파일의
CONTEXT_MAX_FEATURES다.
- 메시지:
- 못 잡음: 경계를 잘못 고른 것 자체. 업무가 다른 기능을 한 context에 넣어도 검사는 통과한다.
④ 쓸 스킬: domain-driven-design
1단계. 뼈대 만들기 — create:feature
기본 길은 생성 명령이다.
corepack pnpm create:feature invoice-feature
명령이 하는 일:
인자 검사
→ 설치된 기능·context·라우트·topic·문구 키 읽기
→ 충돌 검사 (겹치면 아무것도 쓰지 않고 거부)
→ 파일 쓰기 (있는 파일은 덮어쓰지 않음)
→ 생성기 실행
→ 생성기가 거부하면 만든 파일을 모두 지움
→ dev server manifest(public/release-manifest.json, 추적 파일) 다시 쓰기
→ 만든 파일과 다음 할 일 출력
- 기능과 함께 커밋할 추적 파일은 둘이다. dev server manifest와 초기 JS 기록이다. 기능 브랜치 둘이 같은 줄에서 충돌하면 명령을 다시 돌린다. 표와 명령은 03 문서 A에 있다.
① 정할 것
--context <context id>: 0단계에서 기존 context를 골랐을 때만 준다.--with-create: 상세와 작성까지 만든다. 짝 백엔드에서scripts/new-feature.sh <Name>을 같은 이름으로 돌렸을 때 준다(예: 프론트invoice-feature, 백엔드Invoice→ 둘 다/invoices).--keyed:--with-create와 함께만. 백엔드 create를 멱등성 executor 뒤에 두었을 때(KEYED) 준다.--package @scope/name@x.y.z --digest sha256:<64 hex> --revision <hex>: 계약 패키지가 이미 배포됐을 때 준다. 셋은 함께 준다.- 둘 다 없으면 새 context와 자리표시자 계약 신원으로 만든다.
- 자리표시자 신원: 패키지가 아직 없을 때 쓰는 가짜 신원이다. 로컬·개발 빌드는 되고, staging·production 승인은 거절한다.
② 기준
- 패키지가 아직 없으면 자리표시자로 시작한다. 3단계에서 실제 신원으로 바꾼다(02 결정표 2절).
- 손으로 만드는 길도 있다.
docs/architecture/starter-experience.md의 "Adding a feature" 절이 그 순서다. 다만 전역 ID 접두어, 무작위 topic, a11y 기록을 직접 챙겨야 한다. - 인자·파일·출력 전체는 reference/create-feature.md에 있다.
③ 잡는 검사 / 못 잡는 것
- 명령 자체가 거부한다. ID 형식, 기존 기능·context와 겹침, 라우트·경로·chunk·문구 키 충돌, topic 충돌, 패키지 신원 형식.
- 생성기가 거부한다. 선언 헤더가 리터럴이 아님, 없는 context, 예산 초과.
- 이때 명령은 만든 파일을 모두 지우고
the feature index generator rejected the feature, nothing was kept:로 끝난다.
- 이때 명령은 만든 파일을 모두 지우고
- 생성한 context 선언은
tests/unit/create-feature.test.ts가 생성기의 선언 읽기와 앱 모듈 조립으로 실행한다. 라우트가 그 루트 밖이면 그 테스트가 실패한다.
④ 쓸 스킬: clean-architecture, codebase-design
2단계. 도메인 모델 (선택)
생성 명령은 domain/ 폴더를 만들지 않는다.
① 정할 것: 업무 규칙(불변식)이 있는가.
- 불변식: 늘 참이어야 하는 업무 조건이다. 예: "금액은 0 이상", "마감일은 시작일 뒤".
② 기준
- 업무 규칙이 없으면 만들지 않는다. mapper가 DTO를 화면 값으로 바꾸는 것으로 충분하다.
- 있으면
domain/<model>.ts에 둔다.- 생성 함수에서 불변식을 검사하고
Object.freeze로 고정한다. - 이름은 와이어 필드가 아니라 업무 이름으로 짓는다(예: 와이어
name을 화면 값displayName으로).
- 생성 함수에서 불변식을 검사하고
- 예: 청구서는 발행일 뒤에만 마감된다.
domain/<model>.ts한 파일이다.
export type Invoice = Readonly<{
invoiceId: string;
/** Calendar dates, YYYY-MM-DD. */
issuedOn: string;
dueOn: string;
}>;
/** An invoice falls due on or after the day it is issued. */
export function createInvoice(input: Invoice): Invoice {
if (!/^\d{4}-\d{2}-\d{2}$/u.test(input.issuedOn) || !/^\d{4}-\d{2}-\d{2}$/u.test(input.dueOn)) {
throw new RangeError("Invoice dates are calendar dates (YYYY-MM-DD).");
}
if (input.dueOn < input.issuedOn) {
throw new RangeError("An invoice falls due on or after the day it is issued.");
}
return Object.freeze({ ...input });
}
- 길이 제한(예: 제목 100자)은 domain이 아니라 경계 검증에 둔다.
- 경계 검증: 값이 앱에 들어오거나 나가는 자리(요청·응답 스키마, 폼 스키마)에서 하는 검사다.
- 서버가 정한 제한이면
contracts/<base>-schemas.ts에 상수로 두고 요청 스키마와 폼 스키마가 같은 상수를 쓴다. 숫자가 두 곳에서 갈라지지 않는다. - 생성 판(
--with-create)도 이름 길이 상수(<BASE>_NAME_MAX_LENGTH)를 스키마(contracts/<base>-schemas.ts)와 폼(presentation/<base>-form.ts)에만 둔다.domain/에는 없다. - domain에는 서버 제한이 바뀌어도 그대로인 업무 규칙만 둔다(예: "마감일은 시작일 뒤").
③ 잡는 검사 / 못 잡는 것
- React·HTTP·application을 import하면
check:architecture(FE-GATE-010)가feature-domain-is-framework-neutral규칙으로 막는다. - 못 잡음: 불변식을 domain 대신 페이지에 쓰는 것. 규칙 위치는 검사하지 않는다.
④ 쓸 스킬: clean-architecture, codebase-design
3단계. API 계약
생성된 파일:
contracts/<base>-feature-contract.ts: 선언 쪽. 라우트, 무효화, 계약 패키지 신원(contractPackages).contracts/<base>-contract-contribution.ts: HTTP 계약(descriptor). operation을 적는 곳은 여기 하나다. 이것이 실행되고,check:registries의 FE-REG-API 행도 여기서 뽑는다.contracts/<base>-schema-metadata.ts: 스키마 메타데이터(FE-REG-SCHEMA 행). 스키마 ID마다 쓰이는 자리(boundary)와 소유자를 적는다.contracts/<base>-schemas.ts: zod 스키마와 검증기.contracts/<base>-mapper.ts: 와이어 값 → 화면 값.
FE-REG-API 행은 descriptor에서 자동으로 만든다(src/contracts/api-operations.ts의 projectApiOperationRows). 같은 API를 다른 파일에 다시 적지 않는다.
① 정할 것
- 계약 출처. 실제 패키지 / 자리표시자. 02 결정표 2절
- operation마다:
- 재시도 의미(
retrySemantics). 02 결정표 3절 - 쓰기의 실패 분류(
commandEffect). 02 결정표 4절 - 인증 프로필(
authProfileId). 02 결정표 5절 - 바이트 한도·마감:
requestByteLimit,responseByteLimit,totalDeadlineMs. - 스키마 ID, operation ID. 모두 기능 접두어를 붙인다(reference/global-ids.md).
- 재시도 의미(
② 기준
- 밖에서 들어오는 값(응답, 문제 응답, 입력)은 받는 자리에서 검증한다(원칙 4).
- 검증기는
src/contracts/zod-validator.ts의zodValidator(schemaId, schema)하나를 쓴다. 기능마다 복사하지 않는다. - 검증을 일부러 생략할 때는
src/contracts/unvalidated-payload.ts의unvalidatedPayload(schemaId, reason)를 쓴다. 이유가 빈 문자열이면 throw한다. 생략 목록은listUnvalidatedPayloads가 보여 준다. - zod는
src/contracts/zod.ts로만 import한다.
- 검증기는
- 경로는 짝 백엔드 컨트롤러의 매핑과 같은
/<plural>이다. 생성된 descriptor는API_PATH상수 하나를 쓴다. 백엔드에--path를 줬으면 이 상수를 같은 값으로 바꾼다.- 백엔드의
api-base-path(기본/v1, 로컬/api)는 descriptor에 적지 않는다.config/runtime/<profile>.json의API_BASE_URL에 붙이고 끝을/로 둔다(예:https://api.example.com/v1/). 끝/가 없으면 실행기가URL_ORIGIN_ESCAPED로 보내지 않는다. - 백엔드 생성기는 목록 엔드포인트를 만들지 않는다. 백엔드에
GET /<plural>페이지 목록(PageParams)을 더하기 전에는 생성된 목록이 405를 받는다.
- 백엔드의
- 계약 패키지(
@org-contracts/*)는contracts/<service>-contract-contribution.ts이름의 파일에서만 import한다. - 패키지 신원 네 필드(
packageId,version,digest,sourceRevision)는<base>-feature-contract.ts의 상수 하나에 있다. 바꿀 때는 넷을 함께 바꾼다. - 근거:
scale-architecture.md§13(재시도), §20~§22(검증 경계와 예산).
응답 모양: 짝 백엔드의 Envelope
생성한 기능은 짝 백엔드의 응답을 그대로 읽는다.
짝 백엔드의 정본은 clean-architecture-backend-template/docs/web/http-contract.md다(아래 http-contract.md).
- Envelope: 성공·실패 본문을 한 번 더 감싸는 공통 바깥 객체다(
http-contract.md§1).- 성공:
{ "success": true, "data": ..., "meta": ... } - 실패:
{ "success": false, "error": { "code", ... }, "meta": ... }
- 성공:
- 이 모양을 읽게 하는 것은 V3 descriptor(
<base>-contract-contribution.ts)의 한 줄responseEnvelope: "ENVELOPE_V1"이다. 생성된 operation에는 모두 들어 있다.- operation을 손으로 더할 때마다 이 줄을 적는다. 이 값은 operation마다 따로다. 감싸지 않는 백엔드면
"NONE"을 적는다. 줄은 빼지 않는다. - 줄을 빠뜨리면
check:types가 그 descriptor의satisfies InstalledHttpContract<...>에서 실패한다(Property 'responseEnvelope' is missing ..., 1103/16-01). 기여 안의 operation 모두에서 빼도 같다. - 한 계약 기여 안에서 이 값이 다른 operation이 있으면 계약 조립이 거부한다(
<id>/<operationId>: responseEnvelope NONE, but <other> in the same contribution reads ENVELOPE_V1; ...). 기여 하나는 백엔드 하나의 패키지라서다. 그래서 값을 잘못 적으면 앱을 조립하는 테스트와check:registries가 실패한다. - 못 잡음: 기여 안의 operation 모두에 같은 틀린 값을 적는 것(짝 백엔드인데 모두
"NONE"). 그때는 아래 MSW 줄의 손글씨 gateway 테스트만 잡는다.
- operation을 손으로 더할 때마다 이 줄을 적는다. 이 값은 operation마다 따로다. 감싸지 않는 백엔드면
성공 status → Envelope 확인 → data를 outputValidator로 검증 → mapSuccess
실패 status → Envelope 확인 → error를 problemValidator로 검증 → 판정(effect) → mapProblem
- 백엔드는 값이 null인 필드를 키째 뺀다.
data키가 없으면null로 읽는다. DTO 안에서 null일 수 있는 필드는 스키마에서.optional()로 받는다. - problem 스키마(
<base>-schemas.ts의<base>ProblemSchema)는 Envelope의error객체다. 분기는code로 한다.message는 버린다. - 400·409·422와 백엔드가 정한 5xx 여섯이 적용됐는지는 실행기가 백엔드 기준 표로 정한다. 목록은 02 결정표 4절이다.
- 기준 표는 백엔드 커밋 하나에 묶여 있다(
config/contracts/backend-contract-pin.json). 백엔드 표의 행은config/contracts/backend-http-contract-excerpt.json에 그대로 옮겨 두었고,test:unit이 답 표(config/contracts/backend-idempotency-answers.json)를 그 사본과 대조한다. - 짝 백엔드를 새로 받을 때마다
corepack pnpm check:backend-contract-drift --backend <백엔드 checkout>을 돌린다. 게이트 밖이라 CI는 돌리지 않는다. 1이면 pin 뒤 백엔드 표가 바뀌었거나 사본·답 표가 pin과 다르다. 출력이 그 행을 말한다. 2는 비교하지 못했다는 뜻이고 통과가 아니다(checkout이 없거나 pin 커밋이 없다). - pin을 올릴 때: pin의
backend.commit과 답 표의source.commit을 바꾸고 같은 명령에--write-excerpt를 붙여 사본을 다시 옮긴다. 그다음 답 표와 백엔드 계약 6.1절 표를 명령이 통과할 때까지 고친다. 옮기지 않는 행은 pin의notCopied에 이유와 함께 적는다.
- 기준 표는 백엔드 커밋 하나에 묶여 있다(
- 업무 규칙 거절(
<FEATURE>_INVALID,*_ALREADY_EXISTS등)은 표에 없어 결과 불명이 된다. 그 엔드포인트가 쓰기 전에만 내는 code면commandEffect.refusedBeforeWrite에 적는다. 적어야 사용자가 값을 고쳐 다시 저장할 수 있다(02 결정표 4절). mapProblem이 없거나undefined를 돌려주면 백엔드 code·필드 오류·status별 kind로 읽는다(src/adapters/http/backend-envelope.ts).- 바이트 상한(
responseByteLimit)과 구조 예산은 Envelope 전체에 걸린다. - MSW:
createHttpScenarioHandler는 descriptor의responseEnvelope를 보고 Envelope로 답한다(tests/mocks/handlers/http-scenarios.ts). 그래서 시나리오 테스트는 선언이 틀려도 통과한다. 생성된tests/features/<id>/<base>-http-gateway.test.ts는 백엔드 본문을 그대로 적어 검사한다. operation을 더하면 이 파일에도 그 operation의 백엔드 본문 테스트를 더한다. http-contract.md는 status·code의 뜻(예: 409IDEMPOTENT_IN_FLIGHT)의 정본이다. 기능 코드에서 그 code는 problem의code로 읽는다.
짝 백엔드가 아닌 백엔드
DTO와 problem details(type·title·status)를 감싸지 않고 보내는 백엔드에 붙일 때:
- 모든 descriptor의
responseEnvelope를"NONE" as const로 바꾼다. 줄을 지우면check:types가 실패한다. - problem 스키마를 problem details 모양으로 바꾼다.
classifyProblem이 모든 판정을 정한다. 실행기가 먼저 정하는 판정은 없다.
problem 스키마, 작성의 commandEffect, mapProblem의 예는 02 결정표 4절의 「problem details 백엔드의 예」에 있다. 그 기능의 MSW 본문도 DTO와 problem details로 손으로 적는다.
입력과 스키마 메타데이터
inputValidator 하나가 operation 입력 전체를 검증한다. 입력이 요청의 어디로 가는지는 projectRequest가 정한다.
- 경로 파라미터:
pathValues. 키는pathTemplate의{이름}과 같다. - 검색값:
queryEntries. 인코딩한 쿼리는 8,192바이트까지다(HTTP_EXECUTION_CEILINGS.encodedQueryBytes). - 본문:
body.requestBody: "JSON"일 때만 쓴다. 아니면null이다.
경로 파라미터와 본문을 함께 받는 operation(예: PUT /items/{id} + 본문)은 입력 스키마 하나에 둘을 담고 projectRequest가 나눈다.
정본: descriptor 칸은 src/contracts/external-contract-runtime.ts(InstalledHttpContract), 스키마 메타데이터 칸은 src/contracts/schema-registry.ts(SchemaDefinition).
스키마 boundary 값:
route-params: 라우트 경로 파라미터(paramsSchema). 같은 스키마를 경로 파라미터 GET의inputValidator로도 쓴다.route-search: 라우트 검색값에만 쓴다.route-search-api-request: 라우트 검색값이면서 GET 쿼리다. 목록 검색이 이 경우다.api-request: 요청 입력.api-response: 응답 DTO.api-problem: 실패 본문(problemValidator). Envelope operation이면error객체다. FE-REG-API의problemSchema가 이 행을 가리킨다.
스키마 메타데이터의 boundary·direction·unknownFieldPolicy는 손으로 적지만 tests/unit/schema-metadata-policy.test.ts(test:unit)가 실제 쓰임과 대조한다.
boundary: descriptor의 입력·응답·실패 검증기와 라우트의paramsSchema·searchSchema에서 쓰인 자리로 정해진다. 다르면<schemaId>: row <적은 값>, used as <맞는 값>으로 실패한다. 쓰이는데 행이 없으면<schemaId>: no FE-REG-SCHEMA row.direction: 입력은REQUEST, 응답·실패는RESPONSE.unknownFieldPolicy: zod가 모르는 키를 거부하면(.strict())REJECT_UNKNOWN, 버리면(.strip())STRIP_UNKNOWN.- descriptor의 입력·응답·실패 검증기로 쓰인 스키마의 행은
direction·unknownFieldPolicy를 빼지 않는다. 빼면row states no direction또는row states no unknownFieldPolicy로 실패한다(1106/07-02). 칸이 없으면 응답 DTO를.strict()로 바꿔도 행이 바뀌지 않아check:registries가 breaking으로 보지 못한다. 라우트에만 쓰이는 행은 두 칸이 없어도 된다. 모르는 필드를 볼 객체가 없는 검증기(responseBody: "NONE"출력의z.undefined(), 문자열·null 본문)는direction만 본다. - 이 테스트는 설치된 기능을 읽는다. 기능을 더한 상태에서
test:unit을 돌릴 때 잡힌다.
예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력에 관한 칸과 응답 모양 줄만 적었다.
// GET /notices?q=... inputValidator 스키마 NoticeListQuery (boundary: "route-search-api-request")
pathTemplate: "/notices",
inputValidator: zodValidator("NoticeListQuery", noticeListQuerySchema),
responseEnvelope: "ENVELOPE_V1" as const,
projectRequest: (input) => Object.freeze({
pathValues: Object.freeze({}),
queryEntries: Object.freeze(input.q === undefined ? [] : [Object.freeze(["q", input.q] as const)]),
body: null,
}),
// GET /notices/{noticeId} inputValidator 스키마 NoticeParams (boundary: "route-params")
pathTemplate: "/notices/{noticeId}",
inputValidator: zodValidator("NoticeParams", noticeParamsSchema),
responseEnvelope: "ENVELOPE_V1" as const,
projectRequest: (input) => Object.freeze({
pathValues: Object.freeze({ noticeId: input.noticeId }),
queryEntries: Object.freeze([]),
body: null,
}),
③ 잡는 검사 / 못 잡는 것
- descriptor의 입력·응답·실패 스키마 ID가 스키마 메타데이터에 없으면
check:registries가 실패한다.- 메시지:
FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>(responseSchema,problemSchema도 같다)
- 메시지:
- 스키마 메타데이터의
boundary·direction·unknownFieldPolicy가 실제 쓰임과 다르면test:unit의tests/unit/schema-metadata-policy.test.ts가 실패한다(위 "입력과 스키마 메타데이터"). - 인증 프로필 이름이 틀리면 계약 조립이 거부한다.
check:registries(원인reason도 적는다)와 그 기능의 실행부를 적재하는 테스트가 실패한다.check:types·check:architecture·verify:documentation은 통과한다.- 오류의
reason:<featureId>/<operationId>: unknown authProfileId <id>
- 오류의
- 스키마 ID나 operation ID가 겹치면 적재 때 그 ID를 말하며 실패한다.
- 예:
Invalid or duplicate schema definition: <schemaId>, 계약 조립duplicate operation: <operationId>
- 예:
TEMPLATE_FIXTURE출처를 제품 기능에 쓰면 계약 조립이 거부한다.- 오류의
reason:<id>: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to <fixture owner> only; pin an EXTERNAL_PACKAGE
- 오류의
- zod를 직접 import하면
check:architecture가zod-is-reached-through-contracts-zod로 막는다. - 계약 패키지를 다른 파일에서 import하면
external-contract-package-single-import-path로 막는다. - 자리표시자 신원은 staging·production 승인(
check:release-admission, FE-GATE-027)이 거절한다. - 못 잡음: 쓰기 실패를 서버 계약과 다르게 분류하는 것. 서버가 보장하지 않는 code를
NOT_APPLIED로 적어도 검사는 통과한다. 백엔드 계약을 보고 사람이 확인한다. - 못 잡음: 자리표시자 신원은 로컬·개발 빌드와 merge 게이트를 통과한다. 의도된 동작이다.
④ 쓸 스킬: clean-architecture, codebase-design, api-and-interface-design, security-and-hardening
4단계. application input
생성된 파일: application/<base>-feature-api.ts
- input 타입: 페이지가 부르는 메서드 모음.
- gateway 타입: HTTP 어댑터가 구현하는 port.
create<Base>FeatureInput(gateway, { telemetry }): input을 만드는 함수.ApplicationFeatureInputs보강:declare module ".../application-api.ts"로 기능 ID와 input 타입을 잇는다.- 보강(module augmentation): 다른 파일에 있는 타입에 키를 더하는 TypeScript 문법이다.
① 정할 것
- input 메서드 이름. 사용자가 하는 일로 짓는다(
listItems,createInvoice). - 반환 타입.
Result<Value>(src/contracts/result.ts)를 쓴다. - 쓰기 메서드의 호출 문맥. 쓰기는 뮤테이션의
intent를 받아 gateway까지 넘긴다(Readonly<{ signal?: AbortSignal; intent: MutationIntent }>).KEYED쓰기의 멱등 키가 intent에 있다.--with-create의<Base>CommandContext가 이 모양이다. - 실패 telemetry의
kind.<base>.<동작>.failed꼴로 접두어를 붙인다.
② 기준
- application은 React, HTTP, 어댑터를 모른다. gateway port만 안다.
- telemetry는 결과를 바꾸지 않는다.
failOpenTelemetryPort로 감싼다(src/platform/telemetry/telemetry-port.ts).- 근거:
scale-architecture.md§24(텔레메트리 소유), §26(업무 동작에는 fail-open).
- 근거:
- 쓰지 않는 것:
src/application/result.ts(폐기 재수출),src/application/ports/telemetry-port.ts(이름만 같은 다른 타입).
③ 잡는 검사 / 못 잡는 것
- application이 React·어댑터·presentation을 import하면
check:architecture가feature-application-does-not-know-runtime으로 막는다. - 보강 키와 조립 기여의
featureId가 다르면 조립이 실패한다.- 메시지:
feature adapter contribution <id> installed an input for <other>
- 메시지:
- input 모양이 보강 타입과 다르면
check:types(FE-GATE-003)가 막는다. 음성 fixturetests/fixtures/typecheck/invalid-feature-input.ts도 같은 게이트의check:types:fixtures에서 돈다. - 못 잡음: telemetry
kind중복. 유일성 검사가 없다. 접두어로 피한다.
④ 쓸 스킬: clean-architecture, codebase-design
5단계. HTTP 어댑터와 조립 기여
생성된 파일:
adapters/<base>-http-gateway.ts:defineFeatureHttpOperationForRoutes로 operation과 route ID를 묶고, gateway를 구현한다.adapters/create-<base>-feature-input.ts:defineFeatureAdapterContribution으로 조립 기여를 선언한다.- 조립 기여: 부팅 때 플랫폼이 기능에게 capability를 주고 input을 받아 가는 약속이다.
① 정할 것
needs: 기능이 받을 capability. 템플릿이 만드는 것은http,telemetry다.- 문제 응답 → 실패 매핑. 필요하면
mapProblem을 둔다(예: 409, 422를 업무 실패로). Envelope operation에서mapProblem은 kind·code·필드 오류만 바꾸고 적용 여부는 못 바꾼다. 쓰기 전 거절이면 그 code를refusedBeforeWrite에도 적는다. - operation마다
routeId.defineFeatureHttpOperationForRoutes로 정의할 때 적는다.
② 기준
routeId는 요청 결과 기록에 붙는 이름표다.- 요청이 끝날 때마다 진단 기록(
http.request.completed)과 실패 telemetry(api.request.failed)에route_id로 실린다(src/bootstrap/runtime-adapters.ts의createHttpObservationProjector). - URL, 재시도, 취소, 캐시에는 쓰이지 않는다(
src/adapters/http/feature-http-binding.ts는 이 값을 실행기에 넘기기만 한다).
- 요청이 끝날 때마다 진단 기록(
routeId에는 그 요청을 보내는 화면의 route ID를 적는다.- 읽기: 데이터를 그리는 화면. 목록 GET은 목록 route, 상세 GET은 상세 route.
- 쓰기: 저장 버튼이 있는 화면. 작성 폼 route가 따로 있으면 그 route.
- 여러 화면에서 부르면 주로 부르는 화면 하나를 고른다. 이름표는 하나뿐이다.
needs에는 실제로 쓰는 것만 적는다.- 템플릿이 만들지 않는 capability(예:
indexedDb)는src/bootstrap/product-composition.ts에서 만든다. 제품이 새로 만드는 capability의 타입은src/features/product-capabilities.ts에 적는다. 03 문서를 본다. - 문제 응답 매핑 예제: 짝 백엔드는
create:feature <id> --with-create의adapters/<base>-http-gateway.ts(400<BASE>_INVALID→ 이름 칸). problem details 백엔드는 02 결정표 4절의 조각 2.
③ 잡는 검사 / 못 잡는 것
- presentation이 기능
adapters/를 import하면feature-presentation-does-not-know-outbound-adapters로 막는다. - adapters가 presentation을 import하면
feature-adapters-do-not-know-presentation으로 막는다. - 기능 루트 파일(
feature-module.ts등)이나 계층이 아닌 폴더(support/등)의 파일이src/adapters에 닿으면feature-and-app-roots-do-not-reach-adapters로 막는다. 기능 안에서src/adapters에 닿을 수 있는 곳은adapters/폴더뿐이다. - operation ID·route ID·입력 타입을 틀리면
check:types가 막는다. 음성 fixture:tests/fixtures/typecheck/invalid-http-operation-id.ts,tests/fixtures/typecheck/invalid-http-route-id.ts,tests/fixtures/typecheck/invalid-http-operation-input.ts(check:types:fixtures). - 호스트가 주지 않는 capability를
needs에 적으면 조립이 실패한다.- 메시지:
feature <id> needs <capability>, which the host did not provide
- 메시지:
- operation을 계약에 두고 기능
adapters/·application/에서 쓰지 않으면check:registries(FE-GATE-010)가 실패한다.- 메시지:
FE-REG-API.<operationId> has no executable consumer for operationId=<operationId>
- 메시지:
- 못 잡음:
routeId가 실제로 요청을 보내는 화면과 다른 것. 타입은 기능의 route ID인지만 본다. - 못 잡음: 기능
contracts/나 다섯 폴더 밖에 새로 만든 폴더(예:hooks/)를 거쳐src/adapters에 닿는 import..dependency-cruiser.json에 그 경로를 막는 규칙이 없다. 기능 안에는domain/,application/,contracts/,adapters/,presentation/다섯 폴더만 둔다.
④ 쓸 스킬: clean-architecture, codebase-design
6단계. 라우트
생성된 파일과 자리:
- 계약의
routes와routeRuntimeContracts. 같은 route ID를 두 곳에 쓴다. presentation/<base>-feature-runtime.ts: 지연 로드 페이지 표.moduleId는 계약과 같아야 한다.context-routes.ts: context가 적재하는 라우트 목록. 생성된 판은 계약의 라우트를 그대로 옮긴다.presentation/<base>-routes.ts: 링크용 URL 함수. route ID를 받아buildRouteUrl(src/presentation/routes/route-codecs.ts)로 경로를 채운다.- 문구
route.<ROUTE_ID>.title,route.<ROUTE_ID>.navigation(ko-KR, en-US). 화면의 문서 제목과 메뉴 이름은 이 문구다.- 계약
routes의title·navigationLabel은 화면이 읽지 않는다. FE-REG-ROUTE 기준선 행과 lab 측정(scripts/test-performance.ts, 플랫폼 라우트만)이 읽는다. 생성 명령은 문구와 같은 값을 넣는다. 값을 바꾸면check:registries가 behavior-change로 기록한다.
- 계약
- 기능 폴더 밖:
docs/accessibility/route-reviews/<ROUTE_ID>.md(pending 기록). 생성 명령이 만든다.
① 정할 것
access:public(로그인 없이) 또는session-required(로그인 필요).loadingSurface: 로딩 화면 이름. 케밥 표기.errorSurface:route-boundary,feature-boundary,not-found중 하나. 생성된 판은feature-boundary다.chunkId: 지연 로드 청크 이름. 전역에서 유일해야 한다.navigationOrder: 메뉴 순서.null이면 메뉴에 나오지 않는다.- 파라미터·검색값이 있으면 그 스키마와 codec(
paramsCodec,searchCodec).- codec: URL 문자열을 타입 있는 값으로 바꾸고 되돌리는 함수다.
② 기준
- 경로는 계약에만 적는다. 페이지와 링크는 route ID와
buildRouteUrl로 URL을 만든다. 경로 문자열을 페이지에 다시 적지 않는다. - 파라미터나 검색값이 있는 라우트는
context-routes.ts의 handle에codecs를 싣는다. 예제:create:feature <id> --with-create의context-routes.ts(상세 라우트의 params codec).- 링크용 URL 함수도 같은 codec을
buildRouteUrl의 세 번째 인자로 넘긴다. 기본 생성 판의 목록 라우트는 파라미터가 없어서 넘기지 않는다.--with-create판의 상세 라우트는 codec을 넘긴다. 안 넘기면Unregistered route codec: <codecId>로 throw한다. codec ID는 계약routeRuntimeContracts의paramsCodec·searchCodec값이다. 예제:--with-create판의presentation/<base>-routes.ts.
- 링크용 URL 함수도 같은 codec을
- 검색값(
?status=open)을 읽는 목록은 아래 두 조각을 더한다. 생성 뼈대의 목록 라우트에는 검색값이 없다.- 조각 1(
contracts/<base>-list-search.ts)이 검색값 스키마다. 그 스키마를presentation/<base>-route-codecs.ts의<BASE>_ROUTE_CODECS에<Pascal>ListSearch라는 codec ID로 싣는다. - 계약의 목록 라우트
searchSchema와routeRuntimeContracts의searchCodec을 그 codec ID로 바꾼다. 기본 판처럼context-routes.tshandle에codecs가 없으면--with-create판처럼 싣는다. - 라우터는 페이지를 그리기 전에 그 codec으로 검색값을 해석한다. 틀린 값이면 페이지 대신 잘못된 경로 화면을 그린다.
- 조각 2(
presentation/use-<base>-list-filters.ts)가 페이지에서 그 값을 타입대로 읽는 hook이다. 같은 codec으로 다시 읽으므로 cast가 없다.
- 조각 1(
import { z } from "../../../contracts/zod.ts";
/** The list route's search values (`?status=open`). Absent means every invoice. */
export const invoiceListSearchSchema = z
.object({ status: z.enum(["open", "paid"]).optional() })
.strict();
export type InvoiceListSearch = z.output<typeof invoiceListSearchSchema>;
import { useMemo } from "react";
import { useRouteInput } from "../../../presentation/routes/route-input.tsx";
import {
invoiceListSearchSchema,
type InvoiceListSearch,
} from "../contracts/invoice-list-search.ts";
/**
* The router parsed the search with this codec before the page rendered.
* Reading it back through the same codec gives its type without a cast.
*/
export function useInvoiceListFilters(): InvoiceListSearch {
const { search } = useRouteInput();
return useMemo(() => invoiceListSearchSchema.parse(search), [search]);
}
- 상세 경로는 목록 경로 뒤에
/items/:<id 이름>을 붙인다. 예:/notice/items/:noticeId./notice/:noticeId로 두지 않는다.- 라우터(React Router)는 같은 자리에서 정적 경로를 먼저 고른다. 작성 폼
/notice/new가 있으면 id가new인 공지는/notice/:noticeId로 열 수 없다. items/를 끼우면 정적 경로와 겹치지 않는다. 생성 판(--with-create)의 상세 라우트도 이렇게 한다(<목록 경로>/items/:<camel>Id).
- 라우터(React Router)는 같은 자리에서 정적 경로를 먼저 고른다. 작성 폼
tests/e2e/accessibility.spec.ts는 기능마다 고치지 않는다(1103/16-03).- 이 spec은 등록된 모든 라우트를 열어 axe로 검사한다. 경로 파라미터는 이름과 상관없이 모두
a11y-1로 바꾼다. 파라미터 스키마가 이 값을 거부하면 기능 페이지 대신 잘못된 경로 화면을 검사하므로, id 스키마는 짧은 영문·숫자 문자열을 받게 둔다. - API 요청은 설치된 descriptor에서 method와
pathTemplate으로 찾아 답한다. 목록 조회에는 빈 목록을 그 operation의 모양(responseEnvelope: "ENVELOPE_V1"이면 Envelope)으로 답한다. 그 뒤 경고 상자(role="alert")가 없는지 본다. 그래서 목록 페이지는 빈 상태로 검사된다. - 한 자원을 읽는 조회(경로 파라미터가 있고 빈 목록을 받지 않는 GET)에는 빈 목록 말고 답할 것이 없다. 그래서 상세 페이지는 실패 상태로 그려지고, 테스트 결과에
a11y-data-stateannotation이 남는다. a11y.json은 그 라우트를 통과(scope)가 아니라notChecked에 적는다. report(scripts/write-a11y-report.ts)는 라우트의paramsSchema가 그런 GET의 입력 스키마이면 descriptor만 보고 그 라우트를notChecked로 기대한다. spec이 기록을 남기지 않으면a11y.json not written:으로 실패한다(1106/11-01). 생성 명령의 상세 라우트는 GET과 같은<Pascal>Params를 쓰므로 이 규칙에 든다.- 그 GET을 부르지 않는 페이지의 라우트(예: 상세 아래의 하위 항목 작성 폼
/things/:thingId/parts/new)는 상세 GET의 입력 스키마를paramsSchema로 쓰지 않는다. 같은 스키마를 쓰면 report가 기록을 기대하는데 spec은 한 자원 응답을 보지 못해 기록을 남기지 않으므로 실패한다. 그 라우트에 자기paramsSchema(예:ThingPartCreateParams)를 따로 둔다. - 설치된 GET이 아닌 요청을 그리기 전에 보내면 spec이 실패한다(
requests no installed list or single-resource read answers). - spec은 h1이 보일 때까지 기다린다. 그래서 상세 페이지는 데이터가 없을 때도 h1을 그린다. 예:
heading={{ title: notice?.title ?? message("notice.detail.titlePending") }}처럼 데이터가 없으면 고정 제목("공지")을 쓴다.
- 이 spec은 등록된 모든 라우트를 열어 axe로 검사한다. 경로 파라미터는 이름과 상관없이 모두
- 기능이 앱 홈(
/)을 대신하려면 route IDAPP_HOME을 쓴다.docs/architecture/starter-experience.md의 "Product home and layouts" 절을 본다.
③ 잡는 검사 / 못 잡는 것
- route ID가 겹치면 조립이 실패한다. 메시지:
Duplicate route registry key: <ROUTE_ID> - 경로·
chunkId가 겹치면check:registries가 실패한다. 메시지:FE-REG-ROUTE.<ROUTE_ID> duplicates path=<path> from <ROUTE_ID> loadingSurface가 케밥 표기가 아니면check:registries가does not match로 실패한다.context-routes.ts의 handle이 계약에 없는 route ID를 가리키면 context 적재가 거부한다.- 메시지:
Route handle <ROUTE_ID> loaded by context <context> is not a contract route of its features (...)
- 메시지:
- 라우트별 a11y 기록이 없으면 세 곳이 잡는다.
verify:documentation(FE-GATE-017):docs/accessibility/route-reviews/ has no record for route IDs: <ids>review:a11y-manual -- --format-only(FE-GATE-009):missing recordtest:unit의tests/unit/manual-a11y-evidence.test.ts
- en-US 문구 키가 ko-KR과 다르면
check:i18n(FE-GATE-010)이en-US catalog keys do not match ko-KR로 실패한다. - 못 잡음:
navigationOrder중복. 같은 숫자가 둘이어도 통과한다. 생성 명령은 설치된 최댓값 + 10을 쓴다. - 못 잡음: 페이지가 경로를 문자열로 적어 계약과 어긋나는 것. 라우터를 거치는 페이지 테스트가 있을 때만 잡힌다(10단계).
④ 쓸 스킬: 정해 둔 스킬 없음. 이 절과 02 결정표로 판단한다.
7단계. 쿼리·뮤테이션 바인딩
생성된 파일: presentation/use-<base>-items.ts (bindQuery + useApplicationQuery)
① 정할 것
- 쿼리 namespace:
defineQueryNamespaceIdentity(name, version). 캐시 키의 앞부분이다. - 무효화 topic:
qinv.뒤에 무작위 26자. 쓰기가 끝나면 어떤 쿼리를 다시 받을지 잇는 이름이다. - profile:
LIST_STANDARD,DETAIL_STANDARD,LOOKUP_STABLE,VOLATILE_STATUS중 하나. 캐시 시간 정책이다. 정의는src/contracts/server-state.ts. measureResult: 결과 크기 추정 함수. 캐시 예산에 쓴다.definitionId: 쿼리·뮤테이션 정의 이름.- 쓰기가 있으면 뮤테이션 정책:
duplicatePolicy,invalidate. operation ID와 멱등 키 여부는 정하지 않는다. descriptor에서 받는다(아래).
② 기준
-
topic은 복사하지 않는다. 새 topic이 더 필요하면 값을 새로 만든다.
- 형식:
qinv.+ 소문자·숫자 26자.scripts/create-feature.ts의randomTopicSuffix가 쓰는 방식이다.
- 형식:
-
measureResult에서JSON.stringify를 쓰지 않는다. 문자열 바이트와 항목당 고정 크기로 어림한다(생성된measureItems참고). -
뮤테이션 정책의 operation ID와
requiresIdempotencyKey는commandMutationIdentity(<OPERATION>_CONTRACT)(src/contracts/server-state.ts)로 descriptor에서 받는다. 손으로 적지 않는다.- 실행기는 intent의 operation ID가 descriptor와 다르면 보내기 전에 거부한다. 문자열 ID는 그보다 먼저
check:types가 막는다(③). 그래서 저장 때 거부되는 것은commandMutationIdentity에 손으로 만든 객체를 넘긴 오타뿐이다. 그때는 저장이 항상 실패하고, 화면은 "요청을 처리할 수 없습니다"다. requiresIdempotencyKey는retrySemantics가KEYED일 때만 참이다.- V3 HTTP descriptor가 없는 쓰기(Fileserver 업로드처럼
execute가 HTTP 실행기를 거치지 않는 것)는 descriptor 모양 객체를 넘긴다:...commandMutationIdentity({ contract: { operationId: "<ID>", method: "POST", retrySemantics: "KEYED" } }). intent가 멱등 키를 실어야 하면(Fileserver 업로드에idempotencyKey를 넘길 때)retrySemantics는"KEYED", 아니면"NEVER"다. 이 ID를 대조할 descriptor가 없으므로 ID는 intent의 이름일 뿐이고, 오타는 어느 검사도 잡지 않는다(③). - 테스트에서 descriptor 없이 정책을 만들 때는
tests/helpers/mutation-operation-id.ts의testMutationOperationId("<ID>")를 쓴다. 이 helper는 operation ID만 돌려주므로requiresIdempotencyKey는 따로 적는다. 문자열을 그대로 적으면check:types:test가 실패한다.
- 실행기는 intent의 operation ID가 descriptor와 다르면 보내기 전에 거부한다. 문자열 ID는 그보다 먼저
-
쓰기 정책은
duplicatePolicy: "REJECT_WHILE_ACTIVE",invalidate: [topic]을 쓴다.const INVOICE_CREATE_MUTATION_POLICY = Object.freeze({ definitionId: "invoice-create-v1", definitionVersion: 1, ...commandMutationIdentity(INVOICE_CREATE_CONTRACT), duplicatePolicy: "REJECT_WHILE_ACTIVE" as const, invalidate: Object.freeze([INVOICE_ITEM_INVALIDATION_TOPIC]), });- 예제:
create:feature <id> --with-create의presentation/use-<base>-create.ts.
- 예제:
③ 잡는 검사 / 못 잡는 것
- topic·namespace가 겹치면 조립 때 실패한다. 메시지:
Duplicate invalidation topic: <topic>,Duplicate invalidation namespace: <key> - topic 형식이 틀리면
Query invalidation topic is invalid.로 실패한다. - 등록되지 않은 profile은 실행 때
Unregistered server-state profile: <id>로 실패한다. - topic·namespace·edge를 더하기만 하면 레지스트리 기준선은 바뀌지 않는다(additive). 9단계에서 할 일이 없다.
- 뮤테이션 정책의 operation ID를
commandMutationIdentity로 받으면 descriptor 상수 이름의 오타는check:types가 막는다. 쓰기 descriptor 대신 GET descriptor를 넘기면 바인딩 때commandMutationIdentity: <operationId> is a GET; a mutation binds a write operation으로 throw한다. - 뮤테이션 정책에 operation ID를 문자열로 직접 적으면
check:types가 실패한다.BoundMutation.operationId는MutationOperationId이고, 이 값은commandMutationIdentity만 만든다. 오류는 그 문자열을MutationOperationId에 넣을 수 없다고 말한다. - 못 잡음:
commandMutationIdentity에 descriptor 상수 대신 손으로 만든 객체({ contract: { operationId: "…", … } })를 넘기는 것. descriptor가 있는 쓰기면 그 오타는 저장할 때 실행기가 보내기 전에 거부한다(MISSING_IDEMPOTENCY_KEY위반). descriptor가 없는 쓰기(②의 Fileserver 업로드 등)는 대조할 곳이 없어 오타가 그대로 intent 이름이 된다. bindQuery의owner·operationId, 뮤테이션 정책의owner는 적지 않는다. 읽는 곳이 없어@deprecated선택 칸이 됐고, 다음 릴리스에서 지운다. 요청 기록의 operation ID는 descriptor의 것이다.- 못 잡음:
definitionId중복. 유일성 검사가 없다.
④ 쓸 스킬: 정해 둔 스킬 없음. 이 절과 02 결정표로 판단한다.
8단계. 페이지
생성된 파일: presentation/<base>-list-page.tsx (CollectionPage + AsyncSurface)
① 정할 것
- 페이지 템플릿. 02 결정표 6절
- 쓰기가 있으면 결과 불명 화면.
AsyncSurface의onReconcileUnknownEffect(확인),onResendUnknownEffect(같은 키로 다시 보내기). 다시 보내기 버튼은 다시 보내도 되는 요청(KEYED,IDEMPOTENT. 뮤테이션 정책의resendSafe)에만 그려진다.NEVER쓰기는 확인만 남는다. 폼 밖에서mutation.submit을 부르는 화면도NEVER쓰기의 같은 입력을 다시 보낼 수 없다. 훅이DUPLICATE_IN_FLIGHT(codeUNKNOWN_EFFECT_PENDING)로 거절한다.AsyncSurface에 손으로 만든 상태를 넘기면 재전송 버튼은 그려지지 않는다(코디네이터의state를 넘긴다). - 폼이면 서버 필드 오류를 받을 필드(
useAppForm의allowedServerFields). 짝 백엔드는 필드 검증 거절을 400VALIDATION_FAILED와details[{field, code}]로 보낸다(422가 아니다). 공유 MSW 시나리오에는 짝 백엔드가 보내지 않는validation-422만 있고, Envelope operation에서 그 답은 결과 불명이다. 짝 백엔드 모양의 필드 오류 테스트는 생성된 작성 폼 테스트(<base>-create-page.test.tsx)처럼 400 본문을 손으로 적는다.
② 기준
- 화면 문구는 모두 catalog에서 가져온다(
message(key)). - 링크는 6단계의 URL 함수로 만든다.
- 결과 불명 화면 예제:
create:feature <id> --with-create의presentation/<base>-create-page.tsx. problem details 백엔드도 화면은 같다. 다른 것은commandEffect와mapProblem뿐이다(02 결정표 4절). - 다시 시도가 아닌 실패 행동(다시 로그인, 안전한 화면으로 이동)의 버튼은 페이지가 handler를 넘길 때만 그려진다. 생성된 목록 페이지는
onRetry만 넘긴다.- 실패의
action(src/contracts/errors.ts의ERROR_REGISTRY)이reauth(401)·navigate(403·404)일 때 쓸 hook이다.AsyncSurface에onAction={useInvoiceFailureAction(query.state.failure)}로 넘긴다. retry는 쿼리(onRetry)가,reload-once는 청크 복구 경계가 맡는다. 이 hook은undefined를 돌려준다.
- 실패의
import { useCallback } from "react";
import { useLocation, useNavigate } from "react-router-dom";
import type { AppFailure } from "../../../contracts/errors.ts";
import { useSession } from "../../../presentation/providers/session-provider.tsx";
/** Sign in again and come back here, or leave for the home screen. */
export function useInvoiceFailureAction(
failure: AppFailure | undefined,
): (() => void) | undefined {
const location = useLocation();
const navigate = useNavigate();
const { beginSignIn } = useSession();
const action = failure?.action;
const handleAction = useCallback(() => {
if (action === "reauth") {
const returnTo = `${location.pathname}${location.search}${location.hash}`;
void beginSignIn(returnTo).catch(() => {
void navigate("/");
});
return;
}
if (action === "navigate") void navigate("/");
}, [action, beginSignIn, location.hash, location.pathname, location.search, navigate]);
return action === "reauth" || action === "navigate" ? handleAction : undefined;
}
③ 잡는 검사 / 못 잡는 것
- TanStack·HTTP 어댑터를 직접 import하면
check:architecture가feature-presentation-does-not-know-outbound-adapters,presentation-does-not-fetch-directly로 막는다. - 디자인 시스템 하위 경로를 import하면
design-system-is-reached-through-its-index로 막는다. - 화면에 문자를 직접 쓰면
lint(FE-GATE-002)가 막는다.- 메시지:
Screen words come from the message catalog: use message(key) (0929/08-02).
- 메시지:
- 못 잡음:
KEYED쓰기에서 결과 불명 화면을 빠뜨린 것. 기능 테스트로만 잡힌다.
④ 쓸 스킬: frontend-ui-engineering
9단계. 기준선과 증거
① 정할 것
- 레지스트리 기준선을 바꿀 변경인가.
- 레지스트리 기준선: 승인된 레지스트리 스냅샷(
config/contracts/registry-baseline.json)이다.
- 레지스트리 기준선: 승인된 레지스트리 스냅샷(
- 런타임에 기능을 끌 스위치가 필요한가(
FEATURE_OVERRIDES).
② 기준
- 라우트, operation, 스키마, 무효화 topic·namespace·edge를 더하기만 하면 기준선은 바뀌지 않는다.
- 행을 빼거나 breaking 칸을 바꾸면 breaking 변경이다. breaking 칸은
config/contracts/registry-governance.json의breakingFields다. 배열 칸에서 값을 빼는 것도 breaking이다.- FE-REG-API 예: 생성 API의
acceptedStatuses를[200, 201]에서[201]로 줄이거나,problemSchema를 바꾸거나, 검증기를unvalidatedPayload로 바꾸면(unvalidated칸) breaking이다. - status를 더하는 것, 바이트 상한·마감·
retryBudget·traffic·commandEffect·commandRecovery를 바꾸는 것은 behavior-change다. 통과하지만 스냅샷 diff(artifacts/quality/registries.json의compatibility.changes)에 남는다. PR에서 본다. - FE-REG-SCHEMA 예: 응답 DTO를
.strict()로 바꾸고 스키마 메타 행을REJECT_UNKNOWN으로 고치면(direction: "RESPONSE")response-reader-narrowedbreaking이다. 백엔드가 응답에 필드를 하나 더하면 그 API가SCHEMA_MISMATCH로 실패하기 때문이다. 반대(REJECT_UNKNOWN→STRIP_UNKNOWN)와 요청 행은 behavior-change다.
- FE-REG-API 예: 생성 API의
- breaking 변경이면 둘 중 하나를 한다.
REGISTRY_BASELINE_OWNER,REGISTRY_BASELINE_REASON을 주고corepack pnpm update:registry-baseline을 돌린다.- 또는
config/contracts/registry-change-evidence.json에 항목을 더한다. 칸 설명은docs/operations/ci-quality-gates.md에 있다.
- a11y 기록은 생성 명령이 pending으로 만든다. 서명은 릴리스 전에 사람이 한다(03 문서).
- 자리표시자 계약 신원은 staging 배포 전에 바꾼다(03 문서).
- 선택:
config/runtime/<profile>.json의FEATURE_OVERRIDES에 기능 ID를 적으면 그 환경에서 기능을 끈다.
③ 잡는 검사 / 못 잡는 것
- breaking 변경에 승인이 없으면
check:registries가 실패한다.- 메시지:
breaking change missing evidence: <changeId>
- 메시지:
- 지금 diff와 맞지 않는 증거 행이 남으면
stale breaking evidence <changeId>: ...로 실패한다. - 못 잡음: 사람이 서명하지 않은 a11y 기록은 merge 게이트를 통과한다. 릴리스 게이트 FE-GATE-028이 막는다.
- 못 잡음: descriptor의 함수는 행에 없다.
classifyProblem·classifyStatus가 무엇을NOT_APPLIED로 보는지,projectRequest가 무엇을 보내는지는 PR에서 본다.
④ 쓸 스킬: documentation-and-adrs, deprecation-and-migration
10단계. 테스트
생성된 파일:
tests/features/<id>/<base>-feature-input.test.ts: application input 단위 테스트.tests/features/<id>/<base>-list-page.test.tsx: 라우터를 거치는 페이지 테스트.- 앱 전체를 조립하고(
createRuntimeComposition,RuntimeApplication), 로그인한 뒤 URL로 들어간다. - API 응답은 MSW로 준다.
tests/mocks/handlers/http-scenarios.ts의createHttpScenarioHandler(<OPERATION>_CONTRACT, { scenario, payload })를 쓴다. - 시나리오 이름의 정본은
tests/mocks/scenarios/catalog.ts의HttpScenarioId다.
- 앱 전체를 조립하고(
① 정할 것: 어떤 상태를 테스트하나(성공, 빈 목록, 실패와 다시 시도, 결과 불명).
② 기준
-
라우터를 거치는 페이지 테스트를 최소 하나 둔다. 0·6·8단계의 "못 잡음" 대부분을 이 테스트가 잡는다.
-
기능 테스트는
tests/features/<id>/에만 둔다.tests/mocks/의 공유 파일은 쓰기만 하고 고치지 않는다. -
보낸 요청(헤더·본문)은 MSW의
request:start이벤트로 모아서 확인한다.createHttpScenarioHandler는 응답만 정한다. 받은 요청을 돌려주지 않는다.- 생성된 페이지 테스트의
setupServer설정을 아래처럼 바꾼다.
const api = setupServer(); const sent: Request[] = []; beforeAll(() => { api.listen({ onUnhandledRequest: "error" }); api.events.on("request:start", ({ request }) => void sent.push(request.clone())); }); afterEach(() => { api.resetHandlers(); sent.length = 0; });request.clone(): 요청 본문은 한 번만 읽힌다. 복사본을 모아 두어야 테스트에서json()을 부를 수 있다.- 같은 멱등 키 재전송 확인 순서:
api.use(... { scenario: "in-flight-409" }) → 저장 → 결과 불명 화면 → api.use(... 성공 응답) → "같은 요청으로 다시 보내기" 클릭 → POST 두 개의 Idempotency-Key가 같은지 본다const posts = sent.filter((request) => request.method === "POST"); expect(posts).toHaveLength(2); expect(posts[1]!.headers.get("idempotency-key")).toBe(posts[0]!.headers.get("idempotency-key")); expect(await posts[0]!.json()).toEqual({ title: "새 공지", body: "본문입니다." });- 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제:
create:feature <id> --with-create --keyed의tests/features/<id>/<base>-create-page.test.tsx(POST를 받을 때마다 사본을 모으고 같은 키 재전송을 본다).
-
서버 권한 거절(403)은 라우터를 거치는 페이지 테스트로 본다. 생성된 페이지 테스트와 같은 도우미(
<base>-test-app.tsx)를 쓴다.- 403은 본문 없이 답한다. 실행기는 401·403의 본문을 읽지 않고 닫는다. 페이지 테스트 환경(jsdom + MSW)에서 본문이 있는 403(공유 시나리오
forbidden-403)은 그 닫기가 끝나지 않아 화면이 로딩에 머물렀다(2026-11-08 확인).
- 403은 본문 없이 답한다. 실행기는 401·403의 본문을 읽지 않고 닫는다. 페이지 테스트 환경(jsdom + MSW)에서 본문이 있는 403(공유 시나리오
// @vitest-environment jsdom
import { screen, within } from "@testing-library/react";
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";
import { afterAll, afterEach, beforeAll, expect, it } from "vitest";
import { invoiceRouteUrl } from "../../../src/features/invoice-feature/presentation/invoice-routes.ts";
import { KO_MESSAGES } from "../../../src/presentation/i18n/catalog.ts";
import { API, openSignedIn } from "./invoice-test-app.tsx";
const api = setupServer();
beforeAll(() => api.listen({ onUnhandledRequest: "error" }));
afterEach(() => api.resetHandlers());
afterAll(() => api.close());
it("shows the forbidden state when the backend refuses the list", async () => {
api.use(http.get(`${API}/invoices`, () => new HttpResponse(null, { status: 403 })));
await openSignedIn(invoiceRouteUrl("INVOICE_LIST"));
const alert = await screen.findByRole("alert");
expect(
within(alert).getByRole("heading", { name: KO_MESSAGES["access.forbidden.title"] }),
).toBeVisible();
});
- 빠르게 돌리기:
node scripts/run-vitest.ts run tests/features/<id> - CI에서는
test:coverage(FE-GATE-005)가tests/features를 돈다.test:unit은tests/unit만 돈다.
③ 잡는 검사 / 못 잡는 것
- 테스트 실패는
test:coverage가 잡는다. 커버리지 하한도 같은 명령이 본다(config/testing/risk-coverage.json). - 못 잡음: 기능 전용 브라우저 테스트(e2e)를 둘 자리가 기능 폴더 안에 없다. Playwright는
tests/e2e만 읽는다. 그 폴더에 둔 spec은 기능을 지울 때 함께 지워야 한다(11단계).
④ 쓸 스킬: test-driven-development, playwright-best-practices
11단계. 제거 확인
corepack pnpm test:sample-removal -- --feature=invoice-feature
이 명령이 하는 일:
저장소 복사본 만들기
→ 기능 폴더, 기능 테스트 폴더, (마지막 기능이면) context, FEATURE_OVERRIDES 키,
기능 폴더를 가리키는 커버리지 정책 행, owner가 기능 ID인 증거 정책 행을 지움
→ 레지스트리 기준선을 다시 찍음 (빼는 변경은 breaking이라서)
→ 타입·아키텍처·레지스트리·테스트·커버리지·CI 계약·빌드 게이트
→ 지운 기능을 가리키는 파일이 남았는지 찾음
(src: 기능 ID·폴더 이름을 담은 파일, tests: 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일)
① 정할 것: 없음. 확인 단계다.
② 기준
- 기능 전용 파일은 기능 폴더와
tests/features/<id>/안에 둔다(원칙 6). - 폴더 밖에 둘 수밖에 없는 파일은 03 문서의 "기능을 지울 때" 목록에 있다. 실제로 지울 때 그 목록을 함께 지운다.
③ 잡는 검사 / 못 잡는 것
- 남은 파일이 지운 기능을 가리키면 실패한다.
src는 기능 ID나 폴더 이름을 담은 파일,tests는 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일, 그리고 본문에-가 든 기능 ID나 폴더 이름을 한 이름으로 적은 Playwright spec(*.spec.ts)이다.- 메시지:
<id> removal failed:다음 줄fixture-id-residue: residue: <files> - 템플릿 테스트가 예시 ID(
invoice-feature등)를 데이터로 쓰는 것은 잔여로 세지 않는다(1105/16-04). 그래서 매뉴얼 예시 이름으로 만든 기능도 이 단계를 통과한다. - spec 본문은 이름 단위로 찾는다(1106/16-01). 적힌 그대로(대소문자 구분) 찾고, 앞뒤에
[A-Za-z0-9_-]가 붙으면 다른 이름이다.test.describe("invoice-feature", …)는 잔여이고,product-feature를 지울 때generate-product-feature-index.ts처럼 더 긴 이름 안에 든 것은 잔여가 아니다. spec은test:all(vitest)도 드릴의 다른 단계도 돌리지 않으므로 이 검사가 아니면 다음 CI의 브라우저 게이트에서야 실패한다. -가 없는 한 단어 ID·폴더 이름(messages,status)은 spec 본문에서 찾지 않는다. 템플릿 spec이 그 단어를 평범하게 쓰므로(status: 200,getByRole("status")) 찾으면 템플릿 spec이 잔여로 나온다.
- 메시지:
- 못 잡음: 기능을 가리키지 않는 폴더 밖 파일. 예: route ID나 URL만 적은 e2e spec, 한 단어 ID만 본문에 적은 spec,
docs/accessibility/route-reviews/<ROUTE_ID>.md. 기능 전용 spec은 03 문서의 목록대로 손으로 지운다. vitest 테스트(*.test.ts) 안에서 기능 ID를 글자로만 적은 것도 잔여로 세지 않는다. 그 테스트가 지운 기능에 기대면 같은 드릴의test:all이 실패한다. 드릴은src와tests만 찾고, a11y 기록은 남아도 검사가 실패하지 않는다.
④ 쓸 스킬: documentation-and-adrs, deprecation-and-migration
merge 전에 돌릴 것
생성 명령 출력의 Next: 2번이 돌릴 명령 목록이다. 정본은 config/ci/gates.json의 merge 단계다.
한 가지는 따로 본다.
check:bundle(FE-GATE-012): 기능 하나가 초기 JS를 늘린다.feature-module.ts가 정적으로 끌어오는 선언·스키마·문구가 초기 청크에 들어가기 때문이다.- 지연 페이지가 셸과 같은 구성요소(
Button,SearchField등)를 쓰면 그 구성요소가 공유 청크로 떨어져 초기 파일 수도 하나 늘 수 있다. 파일 수 상한(initialJsFiles)은 여유가 있다. - 예산은
config/performance/budgets.json에 있다. 넘었을 때 고르는 법은docs/operations/performance-evidence.md에 있다. 넘으면 예산을 올리기 전에 팀이 정한다. - 생성 명령의 드릴(
test:feature-scaffold)도 merge 단계 명령으로 이 검사를 돈다.
- 초기 JS 기록(
config/scale/feature-shape-ceilings.json)도 기능과 함께 바뀐다.test:unit이 빌드와 대조한다. 생성 명령 출력Next:3번의 명령으로 다시 쓰고 같은 커밋에 넣는다. 기능 제거 드릴(test:sample-removal -- --feature=<id>)은 지운 뒤 기록을 다시 쓰고 검사한다. - 로컬에서 FE-GATE-013을 돌리려면
VITE_COMMIT_SHA=$(git rev-parse HEAD)를 준다. 없으면 release candidate가source.revision을 거절한다. 실패한 게이트의 로그는artifacts/quality/gates/FE-GATE-<NNN>.txt에 있다. - workflow와 같은 조건으로 돌리려면 README 로컬 merge 게이트 반복문 아래의 env 블록대로
CI=true와 CI 빌드 식별값(VITE_COMMIT_SHA,VITE_BUILD_ID,RELEASE_ID,CI_RUNNER_IMAGEdigest)을 주고 깨끗한 clone에서 돌린다. 이 값 없이 통과해도 CI에서 떨어질 수 있다(1103/11-07, 11-08). - 게이트는 한 checkout에서 하나씩 돌린다. 게이트와 증거 검사는
dist와artifacts/의 고정 경로를 읽는다.- 브라우저 테스트(
playwright test)를 한 checkout에서 둘 이상 동시에 돌릴 때는 실행마다 다른TEST_RUN_ID를 준다. 예:TEST_RUN_ID=a corepack pnpm exec playwright test. 그 실행의 빌드·결과·report는.tmp/runs/<id>/아래에 생긴다. - 서버 포트는 run ID가 없어도 빈 포트를 고른다. 같은 기계의 두 worktree도 부딪히지 않는다. 고정하려면
TEST_E2E_PORT같은 포트 변수를 준다. ci:gate에는TEST_RUN_ID를 주지 않는다. 주면 증거가 기본 경로에 생기지 않아 게이트가command-generated evidence was not freshly produced로 실패한다.- 변수 표와 한계는 테스트 전략 13.6절에 있다(1105/12-04).
- 브라우저 테스트(