63 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가 저장소 사본에 예약 이름의 같은 기능(typecheck-probe-invoice-feature)을 만들고, 조각의 이름만 그 기능 이름으로 바꿔 그 자리에 넣은 뒤 타입 검사와 동작 시험을 돌린다. 사본에 제품이 만든 invoice-feature가 있어도 부딪치지 않는다.
전체 흐름
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다. typecheck-probe-로 시작하는 ID는 쓰지 않는다. 템플릿 시험이 저장소 복사본에 만드는 기능 이름이다(scripts/lib/template-probe-features.ts). 그 밖의 이름은 이 매뉴얼의 예시(invoice-feature)를 포함해 모두 쓸 수 있다.- 근거:
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의 "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 측정이 읽는다: 공개 기능 라우트 중navigationLabel이 있는 첫 라우트를 재고(scripts/lib/lab-performance.tslabFeatureRoute), 그 링크와 제목을 그 값으로 찾는다(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의 "제품 홈과 레이아웃" 절을 본다.
③ 잡는 검사 / 못 잡는 것
- 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로 실패한다.- 변수 목록의 정본은
scripts/lib/run-isolation.ts(TEST_RUN_ID_VARIABLE,TEST_PORT_VARIABLES)다. 설계 배경(기록)은 테스트 전략 13.6절이다(1105/12-04).
- 브라우저 테스트(