문제 - 새 기능을 추가하는 절차가 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건 통과.
194 lines
16 KiB
Markdown
194 lines
16 KiB
Markdown
# 실패 메시지와 고칠 파일
|
|
|
|
기능을 만들 때 흔히 보는 실패 메시지다. 메시지는 코드의 문자열을 그대로 옮겼다. `<...>`는 실제 값이 들어가는 자리다.
|
|
|
|
찾는 법: 메시지 앞부분으로 이 문서를 검색한다. 없으면 `git grep '<메시지 앞부분>' -- src scripts`로 코드를 찾는다. 코드가 정본이다.
|
|
|
|
메시지가 어느 단계에서 나오는지:
|
|
|
|
```text
|
|
create:feature → 명령이 파일을 쓰기 전에 거부
|
|
generate:feature-index → 모든 빌드·검사 명령이 먼저 돌린다
|
|
조립·모듈 로드 → 테스트, 빌드, 앱 부팅 어디서든
|
|
check:registries → FE-GATE-010
|
|
lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
|
|
문서·접근성 → FE-GATE-017, FE-GATE-009, FE-GATE-028
|
|
릴리스 승인·공급망 → FE-GATE-027, FE-GATE-012
|
|
제거 드릴 → FE-GATE-020
|
|
```
|
|
|
|
`<base>`는 기능 ID에서 끝의 `-feature`를 뗀 것이다.
|
|
|
|
---
|
|
|
|
## 생성 명령 (create:feature)
|
|
|
|
모두 `create:feature: ` 뒤에 나온다. 종료 코드는 1이다(인자 오류는 2).
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `feature id "<id>" must be kebab-case (lower-case words joined by single hyphens), at most 40 characters` | ID 형식 | 명령 인자 |
|
|
| `context id "<context>" must be kebab-case (lower-case words joined by single hyphens), at most 64 characters` | `--context` 형식 | 명령 인자 |
|
|
| `feature id <id> is already a feature or context` | 같은 ID가 있다 | 다른 ID |
|
|
| `feature id <id> would prefix its ids with "<base>", which <other> already uses` | 접두어가 기존 기능과 같다 | 다른 ID |
|
|
| `context <context> already exists; pass --context <context> to add the feature to it` | 새로 만들 context가 이미 있다 | `--context <context>`를 준다 |
|
|
| `context id <context> is a feature id` | context ID가 기능 ID와 같다 | 다른 `--context` |
|
|
| `src/contexts has a <context> directory without a context declaration` | 선언 없는 context 폴더 | `src/contexts/<context>/context-module.ts`를 만들거나 폴더를 지운다 |
|
|
| `another context already owns the route root <root>/*` | 같은 라우트 루트를 다른 context가 가진다 | 다른 ID, 또는 그 context에 `--context`로 넣는다 |
|
|
| `a new context needs exactly one deployable app (declared: <apps>); pass --context <an existing context>` | 앱이 여럿이라 새 context의 소속을 정할 수 없다 | `--context` |
|
|
| `route <ROUTE_ID> (<path>, <chunkId>) collides with installed route <ROUTE_ID> (<path>, <chunkId>)` | route ID·경로·chunk가 겹친다 | 다른 ID |
|
|
| `message keys already exist: <keys>` | 문구 키가 겹친다 | 다른 ID |
|
|
| `generated topic <topic> is already installed; run the command again` | 무작위 topic이 우연히 겹쳤다 | 명령을 다시 돌린다 |
|
|
| `contract package <packageId>@<version> is not a pinned identity: <reason>` | 패키지 신원 형식. `<reason>` 예: `<id>: package version must be exact SemVer`, `<id>: package digest`, `<id>: package sourceRevision`, `<id>: packageId` | `--package`, `--digest`, `--revision` |
|
|
| `--package, --digest and --revision go together. ...` | 셋 중 일부만 줬다 | 셋을 함께 준다 |
|
|
| `--package must be @scope/name@<exact version>. ...` | 버전 없는 패키지 이름 | `@scope/name@1.2.3` 꼴 |
|
|
| `refusing to overwrite: <paths>` | 쓸 파일이나 기능 폴더가 이미 있다 | 그 경로를 확인하고 지우거나 다른 ID |
|
|
| `the feature index generator rejected the feature, nothing was kept:` | 생성기가 거부했다. 만든 파일은 모두 지웠다 | 뒤따르는 생성기 메시지(아래 절) |
|
|
|
|
---
|
|
|
|
## 생성기 (generate:feature-index)
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `Feature <id> belongs to undeclared context <context>` | context 선언이 없거나 `FEATURE_CONTEXT_ID` 오타 | `src/contexts/<context>/context-module.ts`, 또는 `src/features/<id>/feature-module.ts` |
|
|
| `Context <context> belongs to undeclared app <app>` | `CONTEXT_APP_ID` 오타 | `src/contexts/<context>/context-module.ts` |
|
|
| `<file> must export a literal <NAME>` | 헤더를 상수 참조나 식으로 썼다. 생성기는 글자로 읽는다 | 그 파일. `export const <NAME> = "<값>";` 꼴 |
|
|
| `<file> must export a positive integer <NAME>` | 예산 값이 정수 리터럴이 아니다 | 그 파일 |
|
|
| `src/features/<dir> has no feature-module.ts; add one or mark the directory with NOT_INSTALLED` | 기능 폴더에 선언 파일이 없다 | `feature-module.ts`를 만들거나 `NOT_INSTALLED` 파일을 둔다 |
|
|
| `Duplicate generated feature ids: <id>` | 두 폴더가 같은 `FEATURE_MODULE_ID` | 한쪽 `feature-module.ts` |
|
|
| `Duplicate context id: <id>` | 두 폴더가 같은 `CONTEXT_MODULE_ID` | 한쪽 `context-module.ts` |
|
|
| `Context <context> feature cardinality <n> exceeds budget <max>` | context의 기능 수가 예산을 넘었다 | `CONTEXT_MAX_FEATURES`, 또는 새 context |
|
|
| `App <app> context cardinality <n> exceeds budget <max>` | 앱의 context 수가 예산을 넘었다 | `src/apps/<app>/app-module.ts`의 `APP_MAX_CONTEXTS` |
|
|
|
|
---
|
|
|
|
## 조립·모듈 로드
|
|
|
|
테스트, 빌드, 앱 부팅 어디서든 나온다. 한 기능의 실수가 거의 모든 게이트를 같이 실패시킨다. 첫 메시지를 본다.
|
|
|
|
### 인증 프로필
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `REST security profiles are incoherent for <operationId>: unknown authProfileId <id>.` | 없는 인증 프로필 | `contracts/<base>-api-contract.ts`의 `authProfileId`. 제품 프로필이면 `src/contracts/product-contracts.ts` |
|
|
| `REST security profiles are incoherent for <operationId>: unknown csrfProfileId <id>.` | 없는 CSRF 프로필. 템플릿에는 `NO_CSRF_BEARER`뿐 | `contracts/<base>-api-contract.ts`의 `csrfProfileId` |
|
|
| `REST security profiles are incoherent for <operationId>: auth "none" needs an ANONYMOUS profile, <id> is <transport>.` | V2 `auth: "none"`인데 인증 프로필을 썼다 | V2 `auth` 또는 `authProfileId` |
|
|
| `REST security profiles are incoherent for <operationId>: auth "external-session" cannot use the ANONYMOUS profile <id>.` | 로그인 API에 `ANONYMOUS` | V2 `auth` 또는 `authProfileId` |
|
|
| `Product REST auth profile <id> reuses a template profile id.` | 제품 프로필 ID가 템플릿 것과 같다 | `src/contracts/product-contracts.ts` |
|
|
|
|
### 계약·스키마·mapper
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `Invalid or duplicate schema definition: <schemaId>` | 스키마 ID 중복 또는 메타 형식 | `contracts/<base>-api-contract.ts`의 `schemas`. 접두어를 붙인다 |
|
|
| `Invalid or duplicate runtime schema codec: <schemaId>` | 런타임 codec ID 중복 | `contracts/<base>-schemas.ts` |
|
|
| `Invalid or duplicate boundary mapper: <mapperId>` | mapper ID 중복 또는 형식 | `contracts/<base>-mapper.ts` |
|
|
| `Duplicate API operation: <operationId>` | V2 operation ID 중복 | `contracts/<base>-api-contract.ts` |
|
|
| `contract package <packageId> is declared, but no loaded contribution pins it` | 계약 `contractPackages`에 적은 패키지를 계약 기여가 쓰지 않는다 | `contracts/<base>-contract-contribution.ts`의 `source` |
|
|
| `<id> contributes contract package <packageId>, which no installed feature declares in contracts.contractPackages` | 계약 기여의 신원과 계약 선언의 신원이 다르다 | 둘 다 `<BASE>_CONTRACT_PACKAGE` 하나를 쓰게 한다 |
|
|
| `contract package <packageId> is declared with conflicting identities` | 두 기능이 같은 패키지를 다른 버전·digest로 선언했다 | 두 기능의 `<BASE>_CONTRACT_PACKAGE`를 맞춘다 |
|
|
|
|
계약 조립 실패는 메시지가 `Installed contract contribution is not composable` 하나다. 원인은 오류 객체(`ContractContributionError`)의 `reason` 속성에 있다. 메시지만 보이면 `reason`을 출력해 본다.
|
|
|
|
| `reason` | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `<id>: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to reference-feature only; pin an EXTERNAL_PACKAGE` | 참조 기능 전용 출처를 다른 기능이 썼다 | `contracts/<base>-contract-contribution.ts`의 `source`를 `EXTERNAL_PACKAGE`로 |
|
|
| `duplicate operation: <operationId>` | 두 기여가 같은 operation ID | 접두어를 붙인다 |
|
|
| `duplicate contributionId: <id>` | 두 기여가 같은 `contributionId` | `contracts/<base>-contract-contribution.ts` |
|
|
| `<id>/<operationId>: unknown authProfileId <profile>` | V3 `frontend.authProfileId`가 없는 프로필 | V3 `frontend.authProfileId` |
|
|
| `<id>/<operationId>: retry budget contradicts NEVER retry semantics` | `NEVER`인데 `retryBudget`가 0이 아니다 | V3 `frontend.retryBudget` |
|
|
| `<id>/<operationId>: KEYED commands require a recovery descriptor` | `KEYED`인데 `commandRecovery`가 없다 | V3 `commandRecovery` |
|
|
| `<id>/<operationId>: command operations require a command effect descriptor` | 쓰기에 `commandEffect`가 없다 | V3 `commandEffect` |
|
|
| `<id>/<operationId>: read operations carry no command descriptors` | GET에 `commandEffect`·`commandRecovery`를 적었다 | 둘 다 `null` |
|
|
| `<id>: package version must be exact SemVer` | 버전 범위(`^1.2.0`)나 형식 오류 | `<BASE>_CONTRACT_PACKAGE.version` |
|
|
|
|
### 라우트·context
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `Duplicate route registry key: <ROUTE_ID>` | route ID 중복 | 계약 `routes`. 접두어를 붙인다 |
|
|
| `Duplicate route runtime contract key: <ROUTE_ID>` | `routeRuntimeContracts` 중복 | 계약 `routeRuntimeContracts` |
|
|
| `Route <ROUTE_ID> (<path>) of feature <id> is not under the route root of its context <context> (<root>): the router would answer NOT_FOUND.` | 라우트가 context 루트 밖 | 계약 `routes.*.path`, 또는 `CONTEXT_ROUTE_PATH` |
|
|
| `Route <ROUTE_ID> (<path>) of feature <id> is not under the route root of its context <context> (<root>): context <other> (<root>) takes that URL.` | 다른 context의 루트 아래 | 같은 곳 |
|
|
| `Route handle <ROUTE_ID> loaded by context <context> is not a contract route of its features (<ids>).` | `context-routes.ts`의 handle이 계약에 없는 route ID | `src/features/<id>/context-routes.ts` |
|
|
|
|
### 문구·서버 상태
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `Duplicate <locale> message key: <key>` | 문구 키 중복 | `contracts/<base>-message-catalog.ts`. 접두어를 붙인다 |
|
|
| `Duplicate invalidation topic: <topic>` | topic 중복. 복사한 topic | 계약 `invalidation`. topic을 새로 만든다 |
|
|
| `Duplicate invalidation namespace: <key>` | namespace 중복 | `defineQueryNamespaceIdentity` 이름 |
|
|
| `Query invalidation topic is invalid.` | topic 형식이 `qinv.` + 26자가 아니다 | `defineQueryInvalidationTopic` 값 |
|
|
| `Orphan invalidation topic: <topic>` | edge가 없는 topic | 계약 `invalidation.edges` |
|
|
| `Unregistered server-state profile: <profileId>` | 없는 profile | 쿼리 바인딩의 `profileId` |
|
|
|
|
### 조립 기여
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `feature <id> needs <capability>, which the host did not provide` | 템플릿이 만들지 않는 capability | `src/bootstrap/product-composition.ts`의 `capabilities`, 또는 `needs` |
|
|
| `feature adapter contribution <id> installed an input for <other>` | 기여의 `featureId`와 만든 input의 `featureId`가 다르다 | `adapters/create-<base>-feature-input.ts` |
|
|
| `duplicate feature adapter contribution: <id>` | 두 기여가 같은 기능 ID | 복사한 기여 파일 |
|
|
| `Feature <id> installed an input for <other>` | 지연 로드한 기능이 다른 기능의 input을 냈다 | `adapters/create-<base>-feature-input.ts` |
|
|
|
|
---
|
|
|
|
## 레지스트리 (check:registries)
|
|
|
|
모두 `Registry governance failed:` 다음 줄에 나온다.
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `FE-REG-ROUTE.<ROUTE_ID> duplicates path=<path> from <ROUTE_ID>` | 경로 중복 (`chunkId=`도 같은 꼴) | 계약 `routes` |
|
|
| `FE-REG-ROUTE.<ROUTE_ID>.loadingSurface value <value> does not match <pattern>` | 로딩 화면 이름이 케밥 표기가 아니다 | 계약 `routes.*.loadingSurface` |
|
|
| `FE-REG-ROUTE.<ROUTE_ID>.<field> has unknown value <value>` | `access`·`errorSurface`가 정해진 값이 아니다 | 계약 `routes` |
|
|
| `FE-REG-ROUTE.<ROUTE_ID>.paramsSchema references unknown FE-REG-SCHEMA.schemaId=<id>` | 라우트 스키마 ID를 기능이 등록하지 않았다 (`searchSchema`도 같은 꼴) | 계약 스키마 메타 |
|
|
| `FE-REG-API.<operationId> has no executable consumer for operationId=<operationId>` | V2 operation을 기능 `adapters/`·`application/`에서 쓰지 않는다 | 쓰지 않으면 V2 행을 지운다 |
|
|
| `breaking change missing evidence: <changeId>` | 행을 빼거나 바꿨는데 승인이 없다 | `update:registry-baseline` 또는 `config/contracts/registry-change-evidence.json` |
|
|
| `stale breaking evidence <changeId>: no breaking change in the current diff has this changeId. ...` | 지금 diff와 맞지 않는 증거 행 | 그 행을 지운다 |
|
|
| `registry baseline approval digest mismatch: approved=<digest> actual=<digest>` | 기준선 파일을 손으로 고쳤다 | `update:registry-baseline`으로 다시 찍는다 |
|
|
|
|
---
|
|
|
|
## 경계·lint·문구
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `check:architecture` 출력의 규칙 이름 (`feature-presentation-does-not-know-outbound-adapters` 등) | 금지된 import | 규칙 뜻은 `docs/architecture/layers.md`의 "Rules" 표가 정본 |
|
|
| `Screen words come from the message catalog: use message(key) (0929/08-02).` | 화면에 문자를 직접 썼다 | 문구 catalog에 키를 더하고 `message(key)` |
|
|
| `en-US catalog keys do not match ko-KR` (`I18n contract failed:` 다음) | 두 locale의 키가 다르다 | `contracts/<base>-message-catalog.ts` |
|
|
| `en-US:<key> interpolation parameters do not match` | `{name}` 자리가 locale마다 다르다 | 같은 파일 |
|
|
|
|
---
|
|
|
|
## 문서·접근성
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `artifacts/tests/a11y-manual/ has no record for route IDs: <ids>` (`verify:documentation`) | 라우트의 a11y 기록 파일이 없다 | 기존 pending 기록을 복사해 제목과 `Route ID`를 바꾼다 |
|
|
| `Manual accessibility record format is invalid:` 다음 `artifacts/tests/a11y-manual/<ROUTE_ID>.md: missing record` (FE-GATE-009) | 같은 원인 | 같은 곳 |
|
|
| `Manual accessibility evidence is incomplete:` 다음 `<ROUTE_ID>: <failures>` (FE-GATE-028) | 서명하지 않은 기록 | [03 문서](../03-outside-feature-folder.md#수동-접근성-검토-서명) |
|
|
| `release IDs do not match` (FE-GATE-028) | 라우트마다 다른 릴리스로 검토했다 | 같은 릴리스 후보로 다시 검토한다 |
|
|
| `<doc> names paths that do not exist: <paths>` (`verify:documentation`) | 문서가 없는 경로를 적었다 | 그 문서 |
|
|
|
|
---
|
|
|
|
## 릴리스 승인·공급망
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `release admission refused for <target>:` 다음 `contractPackages.<packageId>: pins the placeholder identity create:feature writes; pin the published package's version, digest and revision` (FE-GATE-027) | 자리표시자 계약 신원으로 공개 대상 승인 | [03 문서 "자리표시자 계약 신원 교체"](../03-outside-feature-folder.md#자리표시자-계약-신원-교체) |
|
|
| `high-risk dependency missing review: add:<name>@<version>` (`generate:supply-chain`) | production 의존성을 더했는데 검토 기록이 없다 | `config/security/dependency-change-evidence.json` |
|
|
|
|
---
|
|
|
|
## 제거 드릴
|
|
|
|
| 메시지 | 원인 | 고칠 곳 |
|
|
|---|---|---|
|
|
| `<id> removal failed:` 다음 `fixture-id-residue: residue: <files>` (`test:sample-removal`) | 기능을 지운 뒤에도 `src`·`tests`에 기능 ID를 담은 파일이 남았다 | 그 파일을 기능 폴더 안으로 옮기거나, 기능 ID를 담지 않게 한다 |
|
|
| `No installed feature declares FEATURE_MODULE_ID "<id>"` | `--feature=`에 없는 기능 ID | 명령 인자 |
|
|
| `feature scaffold failed:` 다음 `<check>: <failure>` (`test:feature-scaffold`) | 생성한 기능이 게이트 하나를 통과하지 못했다 | `scripts/create-feature.ts`의 템플릿. 제품 팀이 아니라 템플릿을 고칠 일이다 |
|