문제 - 새 기능을 추가하는 절차가 starter-experience.md의 영어 단계 7개와 폴더 밖 파일 표뿐이다. 무엇을 고르는지(context, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿), 어느 검사가 무엇을 못 잡는지, 실패 메시지가 어느 파일을 가리키는지는 리뷰 문서(16 영역 8절)에만 있다. 리뷰 문서는 복사한 프로젝트가 지울 수 있는 작업 이력이다. - create:feature(U7)가 생겼지만 그 인자, 만드는 파일, 사람이 해야 하는 일 (a11y 서명, 자리표시자 계약 신원 교체)을 설명하는 문서가 없다. 고른 방법 - docs/manual/을 한국어로 쓴다(결정 5). README(독자, 읽는 순서, 두는 것과 안 두는 것), 01 작업 순서 0~11단계, 02 결정표 6개, 03 기능 폴더 밖 파일, reference/ 4개(create-feature, global-ids, patterns, errors). - 01은 1단계에서 create:feature로 시작하는 길을 기본으로 두고, 단계마다 정할 것, 기준, 잡는 검사(명령·게이트 ID·메시지)와 못 잡는 것, 쓸 스킬을 적는다. 리뷰 시점의 "못 잡음"은 지금 코드로 다시 확인해 고쳤다(예: 루트 밖 라우트는 이제 앱 모듈이 적재 때 거부한다). - 실패 메시지는 src·scripts의 문자열을 그대로 옮기고 값 자리만 <...>로 바꿨다. - 목록 대신 정본 위치를 적는다(공통 원칙 8). route ID는 ROUTE_REGISTRY, 게이트는 config/ci/gates.json, 백엔드 멱등성 응답은 백엔드 템플릿 docs/web/http-contract.md §2를 가리키고 표를 옮기지 않는다. 공통 원칙은 design-docs의 conventions/feature-design-principles.md를 번호로만 가리킨다. - 03은 starter-experience.md의 폴더 밖 표를 정본으로 링크하고 복사하지 않는다. 생성 명령이 하는 것 / 사람이 꼭 하는 것 / 조건부 / 고치지 않는 것으로 나누고, 표에 없는 절차(a11y 서명, 자리표시자 교체, 기능 삭제)만 더한다. - 16 영역 8.4의 금지 목록(목표 디렉터리 구조 절, 예전 폴더 밖 표, 참조 페이지의 경로 문자열)은 링크하지 않고 README에 그 이유를 적는다. - 버린 대안: 리뷰 8절을 그대로 옮기기(리뷰 시점 사실이 지금 코드와 다르고 지울 수 있는 이력에 기댄다), starter-experience.md에 한국어 절을 더하기 (입구 문서는 영어이고 다른 에이전트 소유다), 실패 메시지를 요약해 쓰기 (메시지로 문서를 검색할 수 없다). 위험·한계 - docs/README.md §1 링크는 넣지 않았다(오케스트레이터 몫). 링크하기 전에는 verify:documentation이 이 폴더를 검사하지 않는다. 폴더 링크는 바로 아래 .md만 검사하므로 reference/도 따로 링크해야 한다. - 플랫폼 규칙 근거는 다른 에이전트가 옮기는 scale-architecture.md를 절 번호로 가리킨다. 이 커밋에는 그 파일이 없어 링크 대신 백틱 이름으로 썼다. - 매뉴얼로 막을 수 없는 것이 남는다. 기능 전용 e2e spec은 tests/e2e에만 둘 수 있어 기능 폴더 밖이다. --context reference-context는 참조 기능 테스트 하나를 깨뜨린다. 생성 드릴은 check:bundle을 돌리지 않는다. - "실험 E를 매뉴얼만 보고 다시 하기"는 문서로만 점검했고 실제로 다시 돌리지 않았다. 검증 - docs/README.md §1에 manual/, manual/reference/ 링크를 임시로 넣고 node scripts/verify-documentation-readiness.ts: PASS_SCOPED. 7개 문서 모두 missingPaths·missingScripts·unknownGateIds 0. 임시 링크는 되돌렸다. - 변이: patterns.md에 없는 경로·script·게이트 ID를 넣으면 세 항목을 모두 말하며 FAIL_UNVERIFIED. - 메시지 대조 스크립트: 백틱 안 148개 문구 중 106개는 코드에 그대로 있고, 42개는 코드가 조각을 이어 만드는 문구(접두어·필드 이름·값 채움)라 하나씩 코드에서 확인했다. - node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/deletable-history-documents.test.ts tests/unit/repository-file-inventory.test.ts: 3파일 38건 통과.
8.0 KiB
8.0 KiB
기능 개발 패턴
기능을 만들 때 쓰는 패턴과, 그 패턴의 정의와 예제가 어디 있는지 적는다.
- 정의: 플랫폼(기능 밖)에서 패턴을 제공하는 파일.
- 예제: 복사해 볼 수 있는 기능 코드.
생성 뼈대는create:feature가 만드는 코드다.참조 기능은src/features/reference-feature/다. - 예제가 없는 패턴은 없음이라고 적었다. 그 패턴은 정의를 읽고 직접 쓴다.
참조 기능은 예제일 뿐이다. 복사해 이름을 바꾸지 않는다. 모양을 보고 생성 뼈대에 옮긴다.
기능 조립
| 패턴 | 정의 | 예제 | 검사 |
|---|---|---|---|
| 기능 모듈 등록 | src/features/feature-module.ts (defineFeatureModule, defineFeatureRuntime), 생성기 |
생성 뼈대 feature-module.ts, feature-runtime.ts |
생성기, 기능 ID와 계약 featureId 일치 |
| context 소속 선언 | src/contexts/bounded-context-module.ts |
src/contexts/reference-context/context-module.ts |
생성기(없는 context, 예산), 앱 모듈(루트 밖 라우트) |
| context 전용 레이아웃 | docs/architecture/starter-experience.md "Product home and layouts" |
tests/helpers/fixture-layout-product.tsx (테스트 fixture) |
tests/component/context-layouts.test.tsx |
| 앱 홈 대신하기 | src/contracts/routes.ts의 FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS |
없음 (기능 예제) | 조립 (두 기능이 APP_HOME을 선언하면 실패) |
조립 기여(needs) |
src/features/feature-adapter-contribution.ts |
생성 뼈대 adapters/create-<base>-feature-input.ts |
조립 (없는 capability, 다른 기능의 input) |
| 제품 capability | src/bootstrap/product-composition.ts, src/bootstrap/product-composition-contract.ts |
recipes/frontend-capabilities/indexeddb-feature-capability.ts |
check:types |
| 기능 끄기 | config/runtime/<profile>.json의 FEATURE_OVERRIDES |
config/runtime/local.json |
tests/component/product-feature-switch.test.tsx |
라우트
| 패턴 | 정의 | 예제 | 검사 |
|---|---|---|---|
| 라우트 선언 | src/contracts/routes.ts, src/contracts/route-runtime-contract.ts |
생성 뼈대 계약 routes, routeRuntimeContracts |
조립(중복 route ID), check:registries(경로·chunk 중복) |
| context 라우트 적재 | src/platform/routing/context-route-module.ts |
생성 뼈대 context-routes.ts |
context 적재(계약에 없는 handle) |
| route ID로 URL 만들기 | src/presentation/routes/route-codecs.ts의 buildRouteUrl |
생성 뼈대 presentation/<base>-routes.ts, 참조 기능 presentation/reference-routes.ts |
타입(기능의 route ID만 받음) |
| 파라미터·검색값 codec | src/presentation/routes/route-codecs.ts |
참조 기능 presentation/reference-route-codecs.ts |
해석 실패 시 잘못된 경로 화면 |
| URL 필터를 바꾸는 폼 | 검색값 codec | 없음 (참조 기능은 필터를 보여 주기만 한다) | — |
API와 검증
| 패턴 | 정의 | 예제 | 검사 |
|---|---|---|---|
| V2 operation 행 | src/contracts/api-operations.ts의 defineRestOperation |
생성 뼈대 contracts/<base>-api-contract.ts |
check:registries (FE-REG-API) |
| V3 HTTP 계약(실행) | src/contracts/external-contract-runtime.ts |
생성 뼈대 contracts/<base>-contract-contribution.ts |
계약 조립, V2/V3 일치 테스트 |
| 배포된 계약 패키지 출처 | 같은 파일의 EXTERNAL_PACKAGE |
생성 뼈대(자리표시자 또는 --package 신원). 실제 @org-contracts/* 패키지를 import하는 예제는 없음 |
계약 조립(신원 형식), 릴리스 승인(자리표시자) |
| 런타임 검증기 | src/contracts/zod-validator.ts의 zodValidator |
생성 뼈대 contracts/<base>-schemas.ts |
스키마 ID 중복 |
| 검증 생략 | src/contracts/unvalidated-payload.ts의 unvalidatedPayload |
없음 (기능 예제) | 이유가 비면 throw, listUnvalidatedPayloads가 목록을 보임 |
| DTO → 화면 값 mapper | src/contracts/boundary-mapper.ts |
생성 뼈대 contracts/<base>-mapper.ts |
mapper ID 중복 |
| gateway port + HTTP 어댑터 | src/adapters/http/index.ts의 createFeatureHttpBinding, defineFeatureHttpOperationForRoutes |
생성 뼈대 adapters/<base>-http-gateway.ts |
음성 타입 fixture (operation ID, route ID, 입력) |
| 문제 응답 → 업무 실패 | mapProblem (HTTP 바인딩) |
참조 기능 adapters/reference-http-gateway.ts (409, 422) |
기능 테스트 |
| 결과와 실패 | src/contracts/result.ts, src/contracts/errors.ts |
생성 뼈대 application/<base>-feature-api.ts |
FailureKind 닫힌 어휘(타입) |
| 실패 → 화면 행동 | src/contracts/errors.ts의 action |
참조 기능 presentation/use-reference-failure-action.ts |
페이지 테스트 |
서버 상태
| 패턴 | 정의 | 예제 | 검사 |
|---|---|---|---|
| 쿼리 바인딩 | src/contracts/server-state.ts의 bindQuery, src/presentation/adapters/query/application-query.ts |
생성 뼈대 presentation/use-<base>-items.ts |
profile ID (실행 때). operationId는 string이라 묶이지 않음 |
| 무효화 topic | src/contracts/query-invalidation.ts |
생성 뼈대 계약 invalidation |
조립(중복, 고아 topic) |
| 멱등 키 쓰기 | V3 retrySemantics: "KEYED", commandRecovery, 뮤테이션 정책 |
참조 기능 생성 명령(use-reference-feature.ts, reference-feature-contract-contribution.ts) |
계약 조립(복구 descriptor 필수), 기능 테스트 |
| 결과 불명 화면 | src/presentation/components/async-surface.tsx의 onReconcileUnknownEffect, onResendUnknownEffect |
참조 기능 presentation/reference-resource-form-page.tsx |
기능 테스트만 |
| 수정·삭제 명령 | 같은 V3 계약 (PUT, PATCH, DELETE) |
없음 (참조 기능은 생성 명령만 있다) | — |
| 낙관적 갱신 | useApplicationMutation의 optimistic 옵션 (application-query.ts) |
없음 | 런타임 테스트만 |
| 페이지 넘김 | src/adapters/query-cache/index.ts의 createCursorPaginationRuntime |
없음 (참조 기능은 커서 필터만, 다음 커서 없음) | 런타임 테스트만 |
| 로컬 저장(IndexedDB) | recipes/frontend-capabilities/indexeddb-feature-capability.ts + product-composition.ts |
src/features/local-draft-feature/ (NOT_INSTALLED, 설치되지 않음) |
계약 테스트 |
화면
| 패턴 | 정의 | 예제 | 검사 |
|---|---|---|---|
| 페이지 템플릿 | src/presentation/templates/page-templates.tsx |
생성 뼈대 CollectionPage, 참조 기능 페이지 4개 |
page-templates-own-layout-only |
| 비동기 상태 화면 | src/presentation/components/async-surface.tsx의 AsyncSurface |
생성 뼈대 목록 페이지 | 페이지 테스트 |
| 폼 | src/presentation/forms/use-app-form.ts의 useAppForm |
참조 기능 presentation/reference-resource-form.ts와 폼 페이지 |
페이지 테스트(422 허용 필드, 이탈 확인) |
| 화면 문구 | src/presentation/i18n/index.ts, 기능 문구 catalog |
생성 뼈대 contracts/<base>-message-catalog.ts |
lint(문구 literal), check:i18n(ko-KR·en-US 키) |
| 권한 분기 | 라우트 access, 서버 403 → 실패 |
참조 기능 403 화면 테스트 | 가드 테스트. 역할·권한 힌트 예제는 없음 |
관측
| 패턴 | 정의 | 예제 | 검사 |
|---|---|---|---|
| 기능 telemetry | src/platform/telemetry/telemetry-port.ts의 TelemetryPort, failOpenTelemetryPort |
생성 뼈대 application/<base>-feature-api.ts |
기능 테스트 |
같은 이름의 다른 타입 src/application/ports/telemetry-port.ts의 TelemetryPort는 기능에서 쓰지 않는다.
기능 사이
| 패턴 | 정의 | 예제 | 검사 |
|---|---|---|---|
| 기능 간 협력 | 금지 규칙만 있다 | 없음 | check:architecture (features-do-not-import-other-features) |
두 기능이 같은 것을 써야 하면 기능끼리 import하지 않는다. 공유할 것은 src/contracts나 src/application처럼 기능 밖 공유 폴더에 둘 수 있는지 먼저 본다. 공유 경로를 안내하는 예제는 없다.