Files
clean-architecture-frontend…/docs/manual/01-add-a-feature.md
T
DongHyeonka 12f3bb7862 refactor(contracts)!: V2 API 행을 지우고 FE-REG-API를 HTTP descriptor에서 뽑는다
문제
기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행
(defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고,
contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게
http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가
없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을
위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석
(resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만
남기고, 레지스트리 기준선 재승인을 승인했다.

고른 방법
- src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다.
  조립된 contribution의 descriptor마다 operationId, featureId, method, path,
  authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope,
  request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는
  같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다.
  requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다.
- FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다.
  installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고
  FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
  REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다.
- realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과
  retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics·
  replayPolicy 대신).
- rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립
  때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다.
- 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로
  바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를
  지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다.
- create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를
  만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다.
- 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다
  (digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음).
- 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다.

버린 대안
- V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은
  실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다.
- 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary·
  unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를
  쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다.

위험·한계
- BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes
  의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다.
  옮기는 법은 CHANGELOG에 적는다.
- V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF
  모드)가 사라졌다. V3 descriptor에는 그 칸이 없다.
- BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2
  필드를 갖지만 자체 계약이라 바꾸지 않았다.

검증
- check:types, lint, check:architecture, check:registries(11 registries PASS,
  compatibility=none), check:ci, check:diagnostics, check:adapter-inventory,
  verify:documentation 통과.
- test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함),
  test:integration 114, test:component 245, test:contract 23,
  test:runtime-schema 56, tests/features 99 통과.
- tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두
  번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다.
- check:bundle 통과. 초기 JS 201,598 → 200,911 B.
- test:feature-scaffold 16개, test:sample-removal 23개 검사 통과.

BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다.
defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations,
validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS,
createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles,
validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile,
loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은
operation을 contract contribution에만 적고, schemas 행을 feature-runtime에
넘긴다.
2026-11-03 21:37:48 +09:00

38 KiB

01. 새 기능 추가하기 — 0~11단계

핵심은 둘이다.

  • 뼈대는 손으로 만들지 않는다. corepack pnpm create:feature <id>로 만든다.
  • 뼈대를 실제 기능으로 바꾸는 순서가 아래 0~11단계다.

참조 기능(src/features/reference-feature/)을 복사해 이름을 바꾸는 방법은 쓰지 않는다. 그 방법은 접두어 없는 전역 ID, 참조 전용 계약 출처, 기능 밖 테스트 의존 때문에 여러 번 막힌다. 생성 명령은 이 문제를 미리 피한 파일을 쓴다.

전체 흐름

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)
  • 쿼리 1개와 무효화 topic 1개
  • CollectionPage 페이지 1개와 ko-KR·en-US 문구
  • 테스트 2개 (application input 단위 테스트, 라우터를 거치는 페이지 테스트)

그래서 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> (...)
    • tests/architecture/context-route-roots.test.ts(test:coverage, FE-GATE-005)와 라우터를 거치는 페이지 테스트가 이것을 실행한다.
    • 생성 명령은 라우트를 늘 루트 아래에 둔다. 손으로 경로를 바꿀 때만 걸린다.
  • 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·문구 키 읽기
  → 충돌 검사 (겹치면 아무것도 쓰지 않고 거부)
  → 파일 쓰기 (있는 파일은 덮어쓰지 않음)
  → 생성기 실행
  → 생성기가 거부하면 만든 파일을 모두 지움
  → 만든 파일과 다음 할 일 출력

① 정할 것

  • --context <context id>: 0단계에서 기존 context를 골랐을 때만 준다.
  • --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 reference-context로 참조 context에 넣으면 참조 기능 테스트 tests/features/reference-feature/installed-context-routing.test.ts가 깨진다. 그 테스트는 참조 context의 라우트 수를 정확히 비교한다. 참조 context에는 넣지 않는다.

④ 쓸 스킬: clean-architecture, codebase-design


2단계. 도메인 모델 (선택)

생성 명령은 domain/ 폴더를 만들지 않는다.

① 정할 것: 업무 규칙(불변식)이 있는가.

  • 불변식: 늘 참이어야 하는 업무 조건이다. 예: "금액은 0 이상", "마감일은 시작일 뒤".

② 기준

  • 업무 규칙이 없으면 만들지 않는다. mapper가 DTO를 화면 값으로 바꾸는 것으로 충분하다.
  • 있으면 domain/<model>.ts에 둔다.
    • 생성 함수에서 불변식을 검사하고 Object.freeze로 고정한다.
    • 이름은 와이어 필드가 아니라 업무 이름으로 짓는다(참조 기능은 name을 displayName으로 바꾼다).
  • 예제: src/features/reference-feature/domain/
  • 길이 제한(예: 제목 100자)은 domain이 아니라 경계 검증에 둔다.
    • 경계 검증: 값이 앱에 들어오거나 나가는 자리(요청·응답 스키마, 폼 스키마)에서 하는 검사다.
    • 서버가 정한 제한이면 contracts/<base>-schemas.ts에 상수로 두고 요청 스키마와 폼 스키마가 같은 상수를 쓴다. 숫자가 두 곳에서 갈라지지 않는다.
    • 참조 기능도 이름 길이를 스키마(reference-schemas.ts)와 폼(reference-resource-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를 다른 파일에 다시 적지 않는다.

① 정할 것

② 기준

  • 밖에서 들어오는 값(응답, 문제 응답, 입력)은 받는 자리에서 검증한다(원칙 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한다.
  • 계약 패키지(@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"이다. 뼈대에 들어 있다.
성공 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와 503 IDEMPOTENCY_UNAVAILABLE가 적용됐는지는 실행기가 백엔드 기준 표로 정한다. 목록은 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는 백엔드 본문을 그대로 적어 검사한다.
  • http-contract.md는 status·code의 뜻(예: 409 IDEMPOTENT_IN_FLIGHT)의 정본이다. 기능 코드에서 그 code는 problem의 code로 읽는다.

짝 백엔드가 아닌 백엔드

DTO와 problem details(type·title·status)를 감싸지 않고 보내는 백엔드에 붙일 때:

  1. descriptor에서 responseEnvelope 줄을 지운다.
  2. problem 스키마를 problem details 모양으로 바꾼다.
  3. classifyProblem이 모든 판정을 정한다. 실행기가 먼저 정하는 판정은 없다.

참조 기능(src/features/reference-feature/)이 이 모양이다. 참조 기능의 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.

예: 공지 기능의 검색값 GET과 경로 파라미터 GET. 입력에 관한 칸만 적었다.

// GET /api/notices?q=...  inputValidator 스키마 NoticeListQuery (boundary: "route-search-api-request")
pathTemplate: "/api/notices",
inputValidator: zodValidator("NoticeListQuery", noticeListQuerySchema),
projectRequest: (input) => Object.freeze({
  pathValues: Object.freeze({}),
  queryEntries: Object.freeze(input.q === undefined ? [] : [Object.freeze(["q", input.q] as const)]),
  body: null,
}),

// GET /api/notices/{noticeId}  inputValidator 스키마 NoticeParams (boundary: "route-params")
pathTemplate: "/api/notices/{noticeId}",
inputValidator: zodValidator("NoticeParams", noticeParamsSchema),
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도 같다)
  • 인증 프로필 이름이 틀리면 계약 조립이 거부해 operation을 적재하는 모든 게이트가 실패한다.
    • 오류의 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 reference-feature 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)를 쓴다.
  • 실패 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 check:types:fixture:feature-input도 같은 게이트에서 돈다.
  • 못 잡음: 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를 업무 실패로).
  • 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.
    • 여러 화면에서 부르면 주로 부르는 화면 하나를 고른다. 이름표는 하나뿐이다.
    • 참조 기능은 생성 operation에 목록 route(REFERENCE_RESOURCE_LIST)를 적었다. 실제로 보내는 화면은 폼 route다. 동작은 같고 기록의 이름표만 다르다. 새 기능은 위 기준을 따른다.
  • needs에는 실제로 쓰는 것만 적는다.
  • 템플릿이 만들지 않는 capability(예: indexedDb)는 src/bootstrap/product-composition.ts에서 만든다. 03 문서를 본다.
  • 문제 응답 매핑 예제: src/features/reference-feature/adapters/reference-http-gateway.ts

③ 잡는 검사 / 못 잡는 것

  • presentation이 기능 adapters/를 import하면 feature-presentation-does-not-know-outbound-adapters로 막는다.
  • adapters가 presentation을 import하면 feature-adapters-do-not-know-presentation으로 막는다.
  • 기능 루트 파일(feature-module.ts 등)이 src/adapters에 닿으면 feature-and-app-roots-do-not-reach-adapters로 막는다.
  • operation ID·route ID·입력 타입을 틀리면 check:types가 막는다. 음성 fixture: check:types:fixture:http-operation-id, check:types:fixture:http-route-id, check:types:fixture:http-operation-input.
  • 호스트가 주지 않는 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).
  • 기능 폴더 밖: artifacts/tests/a11y-manual/<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를 싣는다. 예제: src/features/reference-feature/context-routes.ts.

    • 링크용 URL 함수도 같은 codec을 buildRouteUrl의 세 번째 인자로 넘긴다. 생성된 판은 파라미터가 없어서 넘기지 않는다. 안 넘기면 Unregistered route codec: <codecId>로 throw한다. codec ID는 계약 routeRuntimeContracts의 paramsCodec·searchCodec 값이다. 예제: src/features/reference-feature/presentation/reference-routes.ts.
  • 상세 경로는 목록 경로 뒤에 /items/:<id 이름>을 붙인다. 예: /notice/items/:noticeId. /notice/:noticeId로 두지 않는다.

    • 라우터(React Router)는 같은 자리에서 정적 경로를 먼저 고른다. 작성 폼 /notice/new가 있으면 id가 new인 공지는 /notice/:noticeId로 열 수 없다.
    • items/를 끼우면 정적 경로와 겹치지 않는다. 참조 기능도 이렇게 한다(/examples/reference-resources/items/:resourceId).
  • 경로 파라미터 이름이 :resourceId가 아니면 tests/e2e/accessibility.spec.ts의 치환 줄에 .replace를 하나 잇는다.

    // 지금
    : definition.path.replace(":resourceId", "reference-1");
    // 예: 공지 기능의 /notice/items/:noticeId
    : definition.path.replace(":resourceId", "reference-1").replace(":noticeId", "notice-1");
    
    • 이 spec은 등록된 모든 라우트를 열어 axe로 검사한다. 경로 파라미터는 :resourceId만 실제 값으로 바꾼다.
    • 안 고치면 :noticeId라는 글자가 그대로 id로 들어간다. 파라미터 스키마가 그 값을 거부하면 기능 페이지 대신 잘못된 경로 화면을 검사한다.
    • 값은 아무 문자열이나 된다. 이 spec은 모든 API에 []로 답해서 상세 페이지는 실패 상태로 그려진다.
    • spec은 h1이 보일 때까지 기다린다. 그래서 상세 페이지는 데이터가 없을 때도 h1을 그린다. 예: heading={{ title: notice?.title ?? message("notice.detail.titlePending") }}처럼 데이터가 없으면 고정 제목("공지")을 쓴다.
    • 이 줄은 기능 ID를 담지 않는다. 그래서 제거 드릴(11단계)이 잡지 못한다. 기능을 지울 때 손으로 지운다(03 문서).
  • 기능이 앱 홈(/)을 대신하려면 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): artifacts/tests/a11y-manual/ 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: 쿼리·뮤테이션 정의 이름.
  • 쓰기가 있으면 뮤테이션 정책: requiresIdempotencyKey, duplicatePolicy, invalidate.

② 기준

  • topic은 복사하지 않는다. 새 topic이 더 필요하면 값을 새로 만든다.
    • 형식: qinv. + 소문자·숫자 26자. scripts/create-feature.ts의 randomTopicSuffix가 쓰는 방식이다.
  • measureResult에서 JSON.stringify를 쓰지 않는다. 문자열 바이트와 항목당 고정 크기로 어림한다(생성된 measureItems 참고).
  • KEYED 쓰기는 requiresIdempotencyKey: true, duplicatePolicy: "REJECT_WHILE_ACTIVE", invalidate: [topic]을 쓴다.
    • 예제: src/features/reference-feature/presentation/use-reference-feature.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단계에서 할 일이 없다.
  • 못 잡음: bindQuery의 operationId 오타. 타입이 string이라 operation과 묶이지 않는다.
  • 못 잡음: definitionId 중복. 유일성 검사가 없다.

④ 쓸 스킬: 정해 둔 스킬 없음. 이 절과 02 결정표로 판단한다.


8단계. 페이지

생성된 파일: presentation/<base>-list-page.tsx (CollectionPage + AsyncSurface)

① 정할 것

  • 페이지 템플릿. 02 결정표 6절
  • KEYED 쓰기가 있으면 결과 불명 화면. AsyncSurface의 onReconcileUnknownEffect(확인), onResendUnknownEffect(같은 키로 다시 보내기).
  • 폼이면 서버 422 오류를 받을 필드(useAppForm의 allowedServerFields).

② 기준

  • 화면 문구는 모두 catalog에서 가져온다(message(key)).
  • 링크는 6단계의 URL 함수로 만든다.
  • 결과 불명 화면 예제: src/features/reference-feature/presentation/reference-resource-form-page.tsx

③ 잡는 검사 / 못 잡는 것

  • 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 변경이다. 둘 중 하나를 한다.
    • 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이 막는다.

④ 쓸 스킬: 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: "본문입니다." });
    
    • 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제: tests/features/reference-feature/reference-production-vertical.test.tsx의 504 재전송 테스트.
  • 빠르게 돌리기: 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와 tests에 기능 ID나 폴더 이름이 남았는지 찾음

① 정할 것: 없음. 확인 단계다.

② 기준

  • 기능 전용 파일은 기능 폴더와 tests/features/<id>/ 안에 둔다(원칙 6).
  • 폴더 밖에 둘 수밖에 없는 파일은 03 문서의 "기능을 지울 때" 목록에 있다. 실제로 지울 때 그 목록을 함께 지운다.

③ 잡는 검사 / 못 잡는 것

  • 남은 파일이 기능 ID나 폴더 이름을 담고 있으면 실패한다.
    • 메시지: <id> removal failed: 다음 줄 fixture-id-residue: residue: <files>
  • 못 잡음: 기능 ID를 담지 않은 폴더 밖 파일. 예: route ID만 적은 e2e spec, tests/e2e/accessibility.spec.ts에 더한 파라미터 치환(6단계), artifacts/tests/a11y-manual/<ROUTE_ID>.md. 드릴은 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가 정적으로 끌어오는 선언·스키마·문구가 초기 청크에 들어가기 때문이다.
    • 예산은 config/performance/budgets.json에 있다.
    • 생성 명령의 드릴(test:feature-scaffold)은 이 검사를 돌리지 않는다. 넘으면 예산을 올리기 전에 팀이 정한다.