Files
clean-architecture-frontend…/docs/manual/01-add-a-feature.md
T
donghyeon.kang 79dc945a67 refactor(layout): 루트 경로 목록을 등록부 하나에서 고르고 schemas/를 옮긴다
루트 항목 하나를 옮기려면 코드 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절
2026-11-08 17:41:07 +09:00

818 lines
62 KiB
Markdown

# 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`가 그 기능을 저장소 사본에 만들고 조각을 그 자리에 그대로 넣어 타입 검사와 동작 시험을 돌린다.
## 전체 흐름
```text
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절](02-decision-tables.md#3-재시도-의미)).
그래서 3~8단계는 "처음부터 쓰기"가 아니라 "생성된 파일을 실제 계약과 화면으로 바꾸기"다.
## 단계마다 적은 것
- ① **정할 것**: 이 단계에서 고르는 값과 선택지.
- ② **기준**: 무엇을 보고 고르나. 표가 필요한 판단은 [02 결정표](02-decision-tables.md)에 있다.
- ③ **잡는 검사 / 못 잡는 것**: 실수했을 때 어느 명령(게이트 ID)이 어떤 메시지로 잡는가. "못 잡음"은 이 커밋의 검사가 잡지 못한다는 뜻이다. 메시지 전체는 [reference/errors.md](reference/errors.md)에 있다.
- ④ **쓸 스킬**: AI 에이전트가 부를 스킬.
---
## 0단계. 경계와 소속 정하기
① **정할 것**
- 기존 context에 넣을지, 새 context를 만들지.
- context: 같은 URL 앞부분(라우트 루트) 아래에서 함께 지연 로드되는 기능 묶음이다.
- 기능 ID. 케밥 표기만 쓴다. 소문자 단어를 `-`로 잇는 꼴이다(`invoice-feature`).
② **기준**
- context 판단은 [02 결정표 1절](02-decision-tables.md#1-context-경계)과 원칙 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`
기본 길은 생성 명령이다.
```bash
corepack pnpm create:feature invoice-feature
```
명령이 하는 일:
```text
인자 검사
→ 설치된 기능·context·라우트·topic·문구 키 읽기
→ 충돌 검사 (겹치면 아무것도 쓰지 않고 거부)
→ 파일 쓰기 (있는 파일은 덮어쓰지 않음)
→ 생성기 실행
→ 생성기가 거부하면 만든 파일을 모두 지움
→ dev server manifest(public/release-manifest.json, 추적 파일) 다시 쓰기
→ 만든 파일과 다음 할 일 출력
```
- 기능과 함께 커밋할 추적 파일은 둘이다. dev server manifest와 초기 JS 기록이다. 기능 브랜치 둘이 같은 줄에서 충돌하면 명령을 다시 돌린다. 표와 명령은 [03 문서 A](03-outside-feature-folder.md#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절](02-decision-tables.md#2-계약-출처)).
- 손으로 만드는 길도 있다. `docs/architecture/starter-experience.md`의 "Adding a feature" 절이 그 순서다. 다만 전역 ID 접두어, 무작위 topic, a11y 기록을 직접 챙겨야 한다.
- 인자·파일·출력 전체는 [reference/create-feature.md](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` 한 파일이다.
<!-- manual-code-block: src/features/invoice-feature/domain/invoice.ts -->
```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절](02-decision-tables.md#2-계약-출처)
- operation마다:
- 재시도 의미(`retrySemantics`). [02 결정표 3절](02-decision-tables.md#3-재시도-의미)
- 쓰기의 실패 분류(`commandEffect`). [02 결정표 4절](02-decision-tables.md#4-결과-불명)
- 인증 프로필(`authProfileId`). [02 결정표 5절](02-decision-tables.md#5-인증)
- 바이트 한도·마감: `requestByteLimit`, `responseByteLimit`, `totalDeadlineMs`.
- 스키마 ID, operation ID. 모두 기능 접두어를 붙인다([reference/global-ids.md](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 테스트만 잡는다.
```text
성공 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절](02-decision-tables.md#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절](../architecture/backend-api-and-server-state-contract.md) 표를 명령이 통과할 때까지 고친다. 옮기지 않는 행은 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`의 **뜻**(예: 409 `IDEMPOTENT_IN_FLIGHT`)의 정본이다. 기능 코드에서 그 code는 problem의 `code`로 읽는다.
**짝 백엔드가 아닌 백엔드**
DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는 백엔드에 붙일 때:
1. 모든 descriptor의 `responseEnvelope`를 `"NONE" as const`로 바꾼다. 줄을 지우면 `check:types`가 실패한다.
2. problem 스키마를 problem details 모양으로 바꾼다.
3. `classifyProblem`이 모든 판정을 정한다. 실행기가 먼저 정하는 판정은 없다.
problem 스키마, 작성의 `commandEffect`, `mapProblem`의 예는 [02 결정표 4절](02-decision-tables.md#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. 입력에 관한 칸과 응답 모양 줄만 적었다.
```ts
// 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)가 막는다. 음성 fixture `tests/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 문서](03-outside-feature-folder.md)를 본다.
- 문제 응답 매핑 예제: 짝 백엔드는 `create:feature <id> --with-create`의 `adapters/<base>-http-gateway.ts`(400 `<BASE>_INVALID` → 이름 칸). problem details 백엔드는 [02 결정표 4절](02-decision-tables.md#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`.
- 검색값(`?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.ts` handle에 `codecs`가 없으면 `--with-create` 판처럼 싣는다.
- 라우터는 페이지를 그리기 전에 그 codec으로 검색값을 해석한다. 틀린 값이면 페이지 대신 잘못된 경로 화면을 그린다.
- 조각 2(`presentation/use-<base>-list-filters.ts`)가 페이지에서 그 값을 타입대로 읽는 hook이다. 같은 codec으로 다시 읽으므로 cast가 없다.
<!-- manual-code-block: src/features/invoice-feature/contracts/invoice-list-search.ts -->
```ts
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>;
```
<!-- manual-code-block: src/features/invoice-feature/presentation/use-invoice-list-filters.ts -->
```ts
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`).
- `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-state` annotation이 남는다.
- `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") }}`처럼 데이터가 없으면 고정 제목("공지")을 쓴다.
- 기능이 앱 홈(`/`)을 대신하려면 route ID `APP_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 record`
- `test: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`가 실패한다.
- 쓰기 정책은 `duplicatePolicy: "REJECT_WHILE_ACTIVE"`, `invalidate: [topic]`을 쓴다.
```ts
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절](02-decision-tables.md#6-페이지-템플릿)
- 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). 다시 보내기 버튼은 다시 보내도 되는 요청(`KEYED`, `IDEMPOTENT`. 뮤테이션 정책의 `resendSafe`)에만 그려진다. `NEVER` 쓰기는 확인만 남는다. 폼 밖에서 `mutation.submit`을 부르는 화면도 `NEVER` 쓰기의 같은 입력을 다시 보낼 수 없다. 훅이 `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)로 거절한다. `AsyncSurface`에 손으로 만든 상태를 넘기면 재전송 버튼은 그려지지 않는다(코디네이터의 `state`를 넘긴다).
- 폼이면 서버 필드 오류를 받을 필드(`useAppForm`의 `allowedServerFields`). 짝 백엔드는 필드 검증 거절을 400 `VALIDATION_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절](02-decision-tables.md#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`를 돌려준다.
<!-- manual-code-block: src/features/invoice-feature/presentation/use-invoice-failure-action.ts -->
```ts
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-narrowed` breaking이다. 백엔드가 응답에 필드를 하나 더하면 그 API가 `SCHEMA_MISMATCH`로 실패하기 때문이다. 반대(`REJECT_UNKNOWN`→`STRIP_UNKNOWN`)와 요청 행은 behavior-change다.
- 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 문서](03-outside-feature-folder.md)).
- 자리표시자 계약 신원은 staging 배포 전에 바꾼다([03 문서](03-outside-feature-folder.md)).
- 선택: `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` 설정을 아래처럼 바꾼다.
```tsx
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()`을 부를 수 있다.
- 같은 멱등 키 재전송 확인 순서:
```text
api.use(... { scenario: "in-flight-409" }) → 저장 → 결과 불명 화면
→ api.use(... 성공 응답) → "같은 요청으로 다시 보내기" 클릭
→ POST 두 개의 Idempotency-Key가 같은지 본다
```
```tsx
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 확인).
<!-- manual-code-block: tests/features/invoice-feature/invoice-forbidden.test.tsx -->
```tsx
// @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단계. 제거 확인
```bash
corepack pnpm test:sample-removal -- --feature=invoice-feature
```
이 명령이 하는 일:
```text
저장소 복사본 만들기
→ 기능 폴더, 기능 테스트 폴더, (마지막 기능이면) context, FEATURE_OVERRIDES 키,
기능 폴더를 가리키는 커버리지 정책 행, owner가 기능 ID인 증거 정책 행을 지움
→ 레지스트리 기준선을 다시 찍음 (빼는 변경은 breaking이라서)
→ 타입·아키텍처·레지스트리·테스트·커버리지·CI 계약·빌드 게이트
→ 지운 기능을 가리키는 파일이 남았는지 찾음
(src: 기능 ID·폴더 이름을 담은 파일, tests: 이름에 기능 ID가 있거나 기능 폴더에서 import하는 파일)
```
① **정할 것**: 없음. 확인 단계다.
② **기준**
- 기능 전용 파일은 기능 폴더와 `tests/features/<id>/` 안에 둔다(원칙 6).
- 폴더 밖에 둘 수밖에 없는 파일은 [03 문서](03-outside-feature-folder.md)의 "기능을 지울 때" 목록에 있다. 실제로 지울 때 그 목록을 함께 지운다.
③ **잡는 검사 / 못 잡는 것**
- 남은 파일이 지운 기능을 가리키면 실패한다. `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 문서](03-outside-feature-folder.md)의 목록대로 손으로 지운다. 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_IMAGE` digest)을 주고 깨끗한 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절](../testing/frontend-platform-testing-strategy.md)에 있다(1105/12-04).