Files
clean-architecture-frontend…/docs/manual/reference/create-feature.md
T
DongHyeonka e8c4197e0b test(reference): 참조 context 라우팅 테스트가 참조 기능의 라우트만 본다
문제
`create:feature <id> --context reference-context`로 기능을 참조 context에
넣으면 tests/features/reference-feature/installed-context-routing.test.ts가
실패한다. 그 테스트가 참조 context가 적재하는 라우트 전체를 정확히 비교하기
때문이다. 매뉴얼은 이것을 "못 잡음"으로 두고 참조 context에 넣지 말라고만
적었다(메인 세션 X1).

고른 방법
비교 대상을 참조 기능 계약의 route ID로 거른다. 테스트의 의도(참조 기능
라우트가 공개 URL 그대로 지연 적재된다)는 그대로다. 매뉴얼 01 1단계와
reference/create-feature.md의 한계 문장을 고쳤다. 생성한 context 선언을
실행하는 테스트는 앞 커밋(tests/unit/create-feature.test.ts)에 있다.

버린 대안
- 생성 명령이 reference-context를 거부: 생성기가 샘플 이름을 알게 되고, 테스트
  가정 하나를 지키려고 정상 입력을 막는다.

위험·한계
- 참조 context에 넣은 기능은 경로가 /examples/reference-resources/<base>다.
  참조 기능을 지우면 context가 남아 제거 드릴 잔여 검사에 걸린다고 매뉴얼에
  적었다. 이 경로의 드릴은 돌리지 않았다(추론).

검증
- RED: refx-feature --context reference-context --with-create를 만든 상태에서
  이 테스트가 XONE/REFX 라우트를 받아 실패(앞 커밋 검증 기록). 고친 뒤 같은
  상태에서 tests/features 124건 통과, tests/component·architecture와
  create-feature·schema-metadata-policy 49파일 374건 통과. 생성 기능은 지웠다.
- lint, check:types(test), verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 1101/16-02
2026-11-04 23:42:06 +09:00

10 KiB

create:feature 참조

모든 merge 게이트를 통과하는 가장 작은 기능을 만드는 명령이다. 정본은 scripts/create-feature.ts이고, --with-create가 더하는 부분은 scripts/create-feature-write-slice.ts다. 템플릿 문자열이 두 파일 안에 있고, 참조 기능을 import하지 않는다. 그래서 참조 기능을 지운 프로젝트에서도 동작한다.

사용법

corepack pnpm create:feature <id> [--context <context id>] [--with-create [--keyed]] [--package @scope/name@x.y.z --digest sha256:<64 hex> --revision <hex>]
인자 규칙
<id> 케밥 표기, 40자 이하. 기존 기능·context ID와 겹치면 거부
--context 기존 context ID. 없으면 <base>-context를 새로 만든다
--with-create 짝 백엔드 new-feature.sh의 작성(POST /<plural>)·상세(GET /<plural>/{id})와 그 페이지를 더한다. 작성은 NEVER
--keyed --with-create와 함께만. 작성을 KEYED로 만든다. 백엔드 create를 멱등성 executor 뒤에 둔 뒤에 쓴다
--package @scope/name@<정확한 버전>. --digest, --revision과 함께만
--digest sha256: + 소문자 hex 64자리
--revision 소스 리비전. 소문자 hex 7~64자리
  • <base>: ID에서 끝의 -feature를 뗀 것이다. invoice-feature면 invoice. 모든 전역 ID의 접두어가 된다.
  • API 경로: 짝 백엔드 new-feature.sh와 같은 규칙이다. <base>의 camel 표기 뒤에 s, x, ch, sh로 끝나면 es, 자음+y로 끝나면 y를 ies로, 그 밖에는 s를 붙인다. invoice → /invoices, purchase-order → /purchaseOrders, company → /companies. 백엔드의 api-base-path는 API_BASE_URL에 붙인다.
  • 패키지 인자가 없으면 자리표시자 신원을 쓰고 표준 오류로 경고한다.
  • 패키지 인자가 있으면 계약 조립기와 같은 신원 검사(composeContractContributions)로 형식을 확인한다.

하는 일

인자 파싱 (틀리면 사용법 출력, 종료 코드 2)
  → 생성기로 선언을 읽고, 설치된 라우트·topic·문구 키를 읽는다
  → 계획: ID 검사, 충돌 검사, topic 생성, navigationOrder 계산
  → 쓰기: 쓸 경로와 기능 폴더가 하나라도 있으면 아무것도 쓰지 않고 거부
  → 생성기 실행: 거부하면 만든 파일을 모두 지운다
  → 출력: 만든 파일, 다음 할 일 (종료 코드 0)

실패하면 create:feature: <메시지>를 표준 오류에 쓰고 종료 코드 1로 끝난다. 메시지는 errors.md에 있다.

만드는 파일

기능 폴더 src/features/<id>/:

  • feature-module.ts: 선언 헤더(FEATURE_MODULE_ID, FEATURE_CONTEXT_ID)와 FEATURE_MODULE
  • feature-runtime.ts: 실행 쪽. feature-module.ts가 동적으로만 import한다
  • context-routes.ts: context가 적재하는 라우트
  • contracts/<base>-feature-contract.ts: 라우트, 무효화, 계약 패키지 신원
  • contracts/<base>-schemas.ts: zod 스키마와 zodValidator 검증기
  • contracts/<base>-mapper.ts: 와이어 값 → 화면 값
  • contracts/<base>-schema-metadata.ts: 스키마 메타데이터(FE-REG-SCHEMA 행)
  • contracts/<base>-contract-contribution.ts: HTTP descriptor와 계약 기여. FE-REG-API 행은 여기서 뽑는다
  • contracts/<base>-message-catalog.ts: ko-KR·en-US 문구
  • application/<base>-feature-api.ts: input, gateway port, ApplicationFeatureInputs 보강
  • adapters/<base>-http-gateway.ts: HTTP gateway
  • adapters/create-<base>-feature-input.ts: 조립 기여(needs: ["http", "telemetry"])
  • presentation/<base>-feature-runtime.ts: 지연 로드 페이지 표
  • presentation/<base>-routes.ts: route ID → URL 함수(buildRouteUrl)
  • presentation/use-<base>-items.ts: 쿼리 바인딩
  • presentation/<base>-list-page.tsx: CollectionPage 목록 페이지. 결과 수는 meta.page.total

--with-create가 더하는 파일:

  • presentation/<base>-route-codecs.ts: 상세 라우트 params codec
  • presentation/use-<base>-item.ts: 상세 쿼리
  • presentation/use-<base>-create.ts: 작성 뮤테이션 정책(commandMutationIdentity)
  • presentation/<base>-form.ts: 폼 스키마. 이름 길이는 요청 스키마의 상수(<BASE>_NAME_MAX_LENGTH = 백엔드 NAME_MAX_LENGTH 100)를 쓴다
  • presentation/<base>-detail-page.tsx: DetailPage
  • presentation/<base>-create-page.tsx: FormPage. 저장하면 상세를 연다. 결과 불명이면 AsyncSurface를 보인다

domain/은 만들지 않는다. 업무 규칙이 생기면 사람이 만든다.

기능 테스트 폴더 tests/features/<id>/:

  • <base>-test-app.tsx: 앱 전체를 조립해 로그인하고 URL로 들어가는 도우미. 페이지 테스트가 같이 쓴다
  • <base>-feature-input.test.ts: input 단위 테스트
  • <base>-list-page.test.tsx: 라우터를 거치는 페이지 테스트(목록, meta.page.total, 빈 목록, 실패 후 다시 시도)
  • <base>-http-gateway.test.ts: 짝 백엔드 본문을 손으로 적은 gateway 테스트. 하네스의 재시도 상한은 앱 기본값 2다
  • <base>-create-page.test.tsx(--with-create): 201 저장 뒤 상세, 400 <FEATURE>_INVALID 필드 오류와 다시 저장, 응답을 잃은 저장(NEVER는 다시 보내기 없음, KEYED는 같은 키로 다시 보내기)

기능 폴더 밖:

  • src/contexts/<base>-context/context-module.ts: 새 context일 때만
  • artifacts/tests/a11y-manual/<ROUTE_ID>.md: 라우트마다 pending 기록

뼈대 모양

  • 라우트 1개: 파라미터·검색값 없는 목록, session-required, feature-boundary.
  • GET 1개: SAFE, EXTERNAL_BEARER, 응답은 Envelope 안의 항목 배열. 목록 값은 { items, total }이다.
  • --with-create: 라우트 <BASE>_DETAIL(<목록>/items/:<base>Id)·<BASE>_CREATE(<목록>/new), operation <BASE>_GET_ITEM·<BASE>_CREATE_ITEM.
    • 작성 NEVER: retryBudget: 0, 멱등 키 없음. 응답을 잃으면 결과 불명이고 다시 보내기 버튼이 없다.
    • 작성 KEYED(--keyed): commandRecovery IDEMPOTENCY_REPLAY, retryBudget: 1(503 IDEMPOTENCY_UNAVAILABLE 뒤 같은 키로 한 번).
    • 둘 다 acceptedStatuses: [201], refusedBeforeWrite: ["<BASE>_INVALID"], classifyStatus는 401·403·429를 NOT_APPLIED로 본다. 값과 이유는 02 결정표 3절.
  • 모든 operation이 responseEnvelope: "ENVELOPE_V1"이다.
  • 쿼리 1개: LIST_STANDARD profile.
  • 무효화 topic 1개, namespace 1개, edge 1개.
  • 빈 배열 응답은 공유 빈 상태 화면으로 그린다. tests/e2e/accessibility.spec.ts가 모든 API에 []를 답하기 때문이다.

한도·마감 같은 숫자는 scripts/create-feature.ts의 템플릿이 정본이다.

생성된 문구는 자리 채움이다. ko-KR 설명 문구가 "제품 문구로 바꾸세요"라고 적혀 있다. 제품 문구로 바꾼다.

하지 않는 일

  • 레지스트리 기준선, governance, 중앙 카탈로그를 고치지 않는다. 고칠 필요가 없다.
  • README.md나 문서를 고치지 않는다.
  • tests/mocks/ 공유 파일을 고치지 않는다.
  • package.json, src/features/product-capabilities.ts, src/bootstrap/product-composition.ts, src/contracts/product-contracts.ts를 고치지 않는다.
  • a11y 기록에 서명하지 않는다.
  • 실제 계약 패키지를 설치하지 않는다.

출력

표준 출력:

create:feature: <id> in <context> (new context), route <ROUTE_ID> at <path>
  created <파일> ...

Next:
  1. Before a release, have a person review and sign artifacts/tests/a11y-manual/<ROUTE_ID>.md (FE-GATE-028). ...
  2. Run the merge gates: corepack pnpm check:types, lint, ...
     The feature's own tests: node scripts/run-vitest.ts run tests/features/<id> ...
  The registry baseline does not change: ...

패키지 인자가 없을 때 표준 오류:

create:feature warning: no --package was given, so src/features/<id>/contracts/<base>-feature-contract.ts pins the placeholder contract identity. ...

이 경고가 나오면 03 문서의 "자리표시자 계약 신원 교체"를 릴리스 전에 한다.

되돌리기

생성한 기능을 지우려면 만든 것을 지우고 생성기를 다시 돌린다.

rm -r src/features/<id> tests/features/<id> artifacts/tests/a11y-manual/<ROUTE_ID>.md
rm -r src/contexts/<base>-context   # 새 context를 만들었을 때만
corepack pnpm generate:feature-index

이 명령을 지키는 검사

  • tests/unit/create-feature.test.ts (test:unit, FE-GATE-005)
    • 렌더 결과만 본다. 저장소를 건드리지 않는다.
    • 접두어, 참조 기능 이름이 없음, topic 형식과 충돌, navigationOrder, 거부 조건, 덮어쓰기 거부와 되돌리기.
    • 백엔드 경로 규칙, --with-create·--keyed의 descriptor 값, 모든 operation의 Envelope 선언.
    • 생성한 context 선언을 임시 폴더에 써서 생성기의 선언 읽기(createFileSystemDeclarationSource)로 읽고, 그 모듈을 import해 라우트 루트가 기능 라우트를 모두 받는지 앱 모듈 조립으로 확인한다.
  • test:feature-scaffold (FE-GATE-020)
    • 저장소 복사본에 기능 하나를 만들고 커밋한 뒤 게이트를 돈다.
    • 타입, lint, 아키텍처, 레지스트리, i18n, 디자인 시스템, 진단, 문서, unit, component, integration, 기능 테스트, 커버리지, CI 계약, 빌드.
  • test:sample-removal (FE-GATE-020)
    • 참조 기능을 지운 복사본에서 이 명령으로 기능을 만들고 같은 게이트를 다시 돈다. 명령이 참조 기능에 기대지 않는다는 증거다.

알려진 한계

  • --context reference-context로 참조 context에 넣은 기능은 경로가 /examples/reference-resources/<base>다. 참조 기능을 지우면 context가 남고 그 경로가 제거 드릴의 잔여 검사에 걸린다. 남길 기능은 제품 context에 둔다.
  • 드릴은 check:bundle(FE-GATE-012), 브라우저 테스트(test:a11y, test:e2e)를 돌리지 않는다.
  • 새 context는 앱이 하나일 때만 만든다. 앱이 여럿이면 --context로 기존 context를 고른다.