Files
clean-architecture-frontend…/docs
DongHyeonka 3b40f73638 fix(contracts)!: 스키마 메타의 boundary를 쓰임과 대조하고 실패 본문 행을 둔다
문제
<base>-schema-metadata.ts의 boundary는 손으로 적고, check:registries는 값이
목록 안인지만 본다. 응답 스키마에 boundary "api-request"를 적어도 타입·
레지스트리·기능 테스트가 모두 통과한다(리뷰 E-4 세 번째 변이). direction과
unknownFieldPolicy는 07-03 수정(5bee9ab)이 검증기와 대조한다. 또 FE-REG-API의
problemSchema는 breaking 칸이지만 FE-REG-SCHEMA를 참조하지 않고, 참조 기능과
생성 뼈대에 실패 본문 스키마 행이 없다(07-01 (d)).

고른 방법
- schema-metadata-policy.test.ts에 boundary 대조를 더한다. 설치된 descriptor의
  입력·응답·실패 검증기와 라우트 paramsSchema·searchSchema에서 스키마마다
  쓰인 자리를 모으고, 그 조합에서 boundary를 정해 행과 비교한다. 쓰이는데
  행이 없는 스키마도 실패한다. direction·unknownFieldPolicy 검사는 실패
  검증기까지 넓힌다.
- boundary에 "api-problem"을 더한다(SchemaDefinition, governance
  allowedValues). FE-REG-API problemSchema → FE-REG-SCHEMA.schemaId 참조를
  governance에 더한다.
- 참조 기능 ReferenceProblem, 생성 뼈대 <Base>Problem, second-api fixture에
  실패 본문 행을 더한다.

버린 대안
- 메타 행을 descriptor·라우트에서 투영(16-04 권고 (b)): 메타 파일이 거의
  사라지지만 생성 뼈대·참조 기능·레지스트리 원본을 함께 바꾼다. 리뷰가
  "빠르게 막으려면 (c) 먼저"라고 적은 대조 테스트를 골랐다.
- owner를 기능 ID에서 검사: 정한 규칙이 없다(참조 기능 owner는
  "...-vertical-slice"). 그대로 둔다.

위험·한계
- governance 참조 추가는 FE-REG-API 계약 변경이라 기준선을 다시 찍었다
  (REGISTRY_BASELINE_REASON에 1103/16-04). 다른 브랜치 변경(FE-REG-TELEMETRY
  optionalAttributes)도 같은 스냅샷에 들어갔다. 오케스트레이터가 통합 뒤 다시
  찍는다.
- 다운스트림 기능은 실패 본문 행이 없으면 check:registries가 실패한다.
  CHANGELOG에 이행 안내가 필요하다.
- 대조 테스트는 설치된 기능만 본다. 기능을 더한 상태에서 test:unit을 돌릴 때
  잡힌다.

검증
- RED: 새 boundary 테스트가 "ReferenceProblem: no FE-REG-SCHEMA row"로 실패.
  행을 더한 뒤 통과.
- 변이: ReferenceResourcePayload boundary를 api-request로 바꾸면 "row
  api-request, used as api-response"로 실패. 되돌림.
- check:registries 실패(FE-REG-API references 변경) → 기준선 갱신 뒤 PASS
  compatibility=none.
- second-api-feature-registries, registry-governance, release-artifacts,
  create-feature 테스트 통과. check:types, lint, verify:documentation 통과.

BREAKING CHANGE: FE-REG-API problemSchema가 FE-REG-SCHEMA.schemaId를 참조한다.
설치된 기능의 problemValidator 스키마마다 <base>-schema-metadata.ts에
boundary "api-problem", direction "RESPONSE" 행이 없으면 check:registries가
"FE-REG-API.<operationId>.problemSchema references unknown FE-REG-SCHEMA"로
실패한다. 행을 더하고 레지스트리 기준선을 다시 찍는다.
Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-04
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
2026-11-04 23:35:33 +09:00
..

문서 색인

docs/의 문서를 세 묶음으로 나눈다.

1. 현재 계약   지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계   앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력   리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다

문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는 문서 안의 상태 값(COMPOSED, AVAILABLE_NOT_COMPOSED, DESIGNED_NOT_IMPLEMENTED 등)으로 확인한다. 상태 값의 뜻은 README.md의 "Support scope" 절에 있다.

README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.

1. 현재 계약

처음 읽을 입구 문서 6개다.

문서 정하는 것
README.md 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영
architecture/frontend-application-foundation.md 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계
architecture/layers.md, architecture/overview.md 계층과 import 방향. check:architecture가 검사한다
architecture/starter-experience.md 기본 라우트, 인증 모드, 기능 추가·제거 절차
architecture/optional-adapter-recipes.md 선택 기능(recipe)을 넣고 빼는 절차
operations/ci-quality-gates.md, testing/taxonomy.md 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

입구 문서가 가리키는 세부 규칙:

verify:documentation은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 .md 전부)에 적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. CHANGELOG.md는 지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은 없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은 scripts/verify-documentation-readiness.ts다.

게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.

파일 읽는 명령
이 파일, architecture/review-ledger.json, architecture/review-evidence.md verify:documentation (FE-GATE-017)
repo 루트의 artifacts/tests/a11y-manual/ 라우트별 기록 verify:documentation (FE-GATE-017), review:a11y-manual (FE-GATE-009, FE-GATE-028)
reviews/adapters/INVENTORY.md check:adapter-inventory (FE-GATE-010)
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json)

2. 목표 설계

설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.

3. 작업 이력·리뷰

템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다. 복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의 "Files you can delete after copying" 절에 있다.

경로 내용
superpowers/ 과거 작업 계획과 스펙
reviews/ 리뷰 결과와 리뷰 가이드. reviews/adapters/INVENTORY.md만 게이트가 읽는다. reviews/adapters/는 지우지 않는다: INVENTORY의 행과 operations/adapter-remediation-ledger.md가 그 안의 리뷰로 링크한다
../SPEC.md, ../tasks/ 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다