Files
clean-architecture-frontend…/docs/manual/reference/global-ids.md
T
DongHyeonka 8b2048763b docs(manual): 새 기능 추가 매뉴얼을 docs/manual에 쓴다 (U9, 1101/16-01)
문제
- 새 기능을 추가하는 절차가 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건 통과.
2026-11-03 07:27:36 +09:00

4.9 KiB

전역 ID

전역 ID는 기능 하나가 아니라 설치된 기능 전체가 함께 쓰는 공간의 이름이다. 두 기능이 같은 값을 쓰면 조립·레지스트리 검사에서 충돌하거나, 아무 검사 없이 조용히 섞인다.

규칙은 하나다(원칙 5).

  • 모든 전역 ID에 기능 접두어를 붙인다.
  • 무작위 값(무효화 topic)은 복사하지 않고 새로 만든다.

create:feature는 이 규칙대로 값을 만든다. 아래 표의 "생성 값" 열은 invoice-feature로 만들었을 때다. 접두어 꼴: <base> = invoice, <BASE> = INVOICE, <Base> = Invoice.

표

"검사 없음"은 이 커밋에서 유일성 검사를 찾지 못했다는 뜻이다. 접두어만이 충돌을 막는다.

ID 어디에 있나 생성 값 겹치면
기능 ID feature-module.ts, 계약 featureId, ApplicationFeatureInputs 키, FEATURE_OVERRIDES 키 invoice-feature 생성 명령·생성기가 거부 (Duplicate generated feature ids)
context ID context-module.ts, FEATURE_CONTEXT_ID invoice-context 생성 명령·생성기가 거부 (Duplicate context id)
route ID 계약 routes, routeRuntimeContracts, 문구 키 INVOICE_LIST 조립 (Duplicate route registry key)
라우트 경로 계약 routes.*.path /invoice (새 context), /<루트>/invoice (기존 context) check:registries (duplicates path=)
chunkId 계약 routes route-invoice-list check:registries (duplicates chunkId=)
moduleId routeRuntimeContracts, 지연 페이지 표 invoice-list-page check:registries (FE-REG-ROUTE-RUNTIME)
loadingSurface 계약 routes invoice-list 검사 없음 (형식만 본다)
operation ID V2 행, V3 descriptor, gateway INVOICE_LIST_ITEMS 모듈 로드 (Duplicate API operation), 계약 조립 (duplicate operation)
API 경로 V2 path, V3 pathTemplate /api/invoice-items 검사 없음. 백엔드 계약을 따른다
스키마 ID V2 스키마 메타, zod 검증기, codec InvoiceNoRequest, InvoiceItemListPayload, InvoiceProblem 모듈 로드 (Invalid or duplicate schema definition)
mapper ID V2 mapperId, 레지스트리 mapper InvoiceItemListMapper 모듈 로드 (Invalid or duplicate boundary mapper)
contributionId 계약 기여 invoice-feature-http-v1 계약 조립 (duplicate contributionId)
policyId V3 frontend INVOICE_LIST_V1 검사 없음
diagnosticsOperation V3 frontend invoice.list 검사 없음
쿼리 namespace 계약 invalidation.namespaces, 쿼리 바인딩 invoice-item (버전 1) 조립 (Duplicate invalidation namespace)
무효화 topic 계약 invalidation.topics, 뮤테이션 invalidate qinv. + 무작위 26자 생성 명령이 설치된 topic과 비교, 조립 (Duplicate invalidation topic)
쿼리·뮤테이션 definitionId 쿼리 바인딩 invoice-item-list-v1 검사 없음
문구 키 기능 문구 catalog route.INVOICE_LIST.title, invoice.list.title 등 생성 명령, 조립 (Duplicate ko-KR message key)
telemetry kind application input invoice.list.failed 검사 없음
owner V2 행, 스키마 메타, mapper feature-frontend-invoice-feature 검사 없음
인증 프로필 ID V2·V3 authProfileId EXTERNAL_BEARER (템플릿 것을 씀) 제품 프로필이 템플릿 ID를 쓰면 모듈 로드 (reuses a template profile id)
navigationOrder 계약 routes 설치된 최댓값 + 10 검사 없음. 같은 숫자가 둘이어도 통과

메시지 전체와 고칠 파일은 errors.md에 있다.

손으로 ID를 더할 때

뼈대에 operation·라우트·topic을 더하면 생성 명령이 다시 돌지 않는다. 아래를 직접 지킨다.

  • 접두어를 붙인다. NoRequest, ItemList 같은 일반 이름을 쓰지 않는다.
  • 무효화 topic은 새로 만든다.
    • 형식: qinv. + 소문자·숫자 26자.
    • scripts/create-feature.ts의 randomTopicSuffix가 같은 형식으로 만든다.
    • 다른 기능이나 참조 기능의 값을 복사하지 않는다.
  • route ID는 <BASE>_<화면> 꼴로 짓는다(INVOICE_DETAIL). 라우트를 더하면 a11y 기록 파일도 더한다(artifacts/tests/a11y-manual/<ROUTE_ID>.md).
  • 문구 키는 ko-KR과 en-US에 같은 키를 넣는다. check:i18n이 비교한다.

정본 위치

설치된 값의 목록은 이 문서에 두지 않는다. 코드에서 본다.

  • 라우트: src/features/installed-feature-contracts.ts의 ROUTE_REGISTRY
  • 무효화 topic·namespace: 같은 파일의 INVALIDATION_REGISTRY
  • 문구 키: src/presentation/i18n/catalog.ts의 KO_MESSAGES
  • 템플릿 인증 프로필: src/contracts/rest-profiles.ts의 REST_AUTH_PROFILES
  • 레지스트리 스냅샷: config/contracts/registry-baseline.json