Files
clean-architecture-frontend…/docs/README.md
T
DongHyeonka b26517e6f2 fix(docs): 설계 주석에 문서 이름을 붙이고 지운 뒤 끊기는 링크를 없앤다 (1101/14-01)
문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N"
처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4).
가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에
있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지
못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다:
docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로,
docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와
docs/superpowers/plans의 계획으로.

고른 방법:
- 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞
  커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절
  번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다.
- tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 +
  "§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에
  .dependency-cruiser.json을 넣는다.
- README "Files you can delete after copying"에서 INVENTORY.md 한 파일
  대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과
  ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다.
  INVENTORY의 행 구조는 바꾸지 않는다.
- 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은
  링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다.
버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도
상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기
목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시
다른 이력을 가리키면 남길 목록이 계속 커진다.

위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는
주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다.
src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼
이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미
docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의
이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다.
check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던
실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가
바뀐다.

검증:
- RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed).
- GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를
  src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림.
- 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0).
- 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크
  148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계
  참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서
  verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트
  2 passed.
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- node scripts/check-adapter-inventory.ts: PASS
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
  tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts:
  50 passed. tests/architecture: 39 passed.
- npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과.
  .dependency-cruiser.json JSON 파싱 통과.
- 미실행: check:architecture(pnpm 필요).
2026-11-03 07:17:49 +09:00

81 lines
7.3 KiB
Markdown

# 문서 색인
`docs/`의 문서를 세 묶음으로 나눈다.
```text
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
```
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
문서 안의 상태 값(`COMPOSED`, `AVAILABLE_NOT_COMPOSED`, `DESIGNED_NOT_IMPLEMENTED` 등)으로
확인한다. 상태 값의 뜻은 `README.md`의 "Support scope" 절에 있다.
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
## 1. 현재 계약
처음 읽을 입구 문서 6개다.
| 문서 | 정하는 것 |
|---|---|
| [`README.md`](../README.md) | 시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
| [`architecture/frontend-application-foundation.md`](architecture/frontend-application-foundation.md) | 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
| [`architecture/layers.md`](architecture/layers.md), [`architecture/overview.md`](architecture/overview.md) | 계층과 import 방향. `check:architecture`가 검사한다 |
| [`architecture/starter-experience.md`](architecture/starter-experience.md) | 기본 라우트, 인증 모드, 기능 추가·제거 절차 |
| [`architecture/optional-adapter-recipes.md`](architecture/optional-adapter-recipes.md) | 선택 기능(recipe)을 넣고 빼는 절차 |
| [`operations/ci-quality-gates.md`](operations/ci-quality-gates.md), [`testing/taxonomy.md`](testing/taxonomy.md) | 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
입구 문서가 가리키는 세부 규칙:
- 규모 설계(구조·소유·실행·트래픽·오류·검증·텔레메트리·릴리스 일관성)와 코드 주석 `scale-architecture.md §N`의 근거: [`architecture/scale-architecture.md`](architecture/scale-architecture.md). 절마다 현재 계약인지 기록만인지 머리말 표에 적었다
- 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md)
- 정적 배포와 런타임 설정: [`architecture/static-delivery.md`](architecture/static-delivery.md)
- 기능 개발자가 알아야 하는 양: [`architecture/capability-consumer-experience.md`](architecture/capability-consumer-experience.md)
- 운영·복구: [`operations/`](operations/), [`runbooks/`](runbooks/)
- 보안과 공급망: [`security/browser-boundary.md`](security/browser-boundary.md), [`security/supply-chain.md`](security/supply-chain.md)
- 디자인 토큰과 수동 접근성 검토: [`styling/design-tokens.md`](styling/design-tokens.md), [`accessibility/manual-checklist.md`](accessibility/manual-checklist.md)
- 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.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. 목표 설계
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
- 런타임 capability 결정의 정본: [`architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md`](architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md)
- 상태 원장: [`architecture/browser-data-capability-completion-ledger.md`](architecture/browser-data-capability-completion-ledger.md)
- 전체 검토와 로드맵: [`architecture/frontend-platform-capability-review.md`](architecture/frontend-platform-capability-review.md), [`architecture/frontend-platform-implementation-roadmap.md`](architecture/frontend-platform-implementation-roadmap.md)
- 포트·경계·데이터 흐름: [`architecture/frontend-ports-adapters-and-boundaries.md`](architecture/frontend-ports-adapters-and-boundaries.md), [`architecture/typescript-state-and-data-flow.md`](architecture/typescript-state-and-data-flow.md), [`architecture/routing-pages-and-patterns.md`](architecture/routing-pages-and-patterns.md)
- API와 서버 상태: [`architecture/api-contract-schema-mapper-and-server-state.md`](architecture/api-contract-schema-mapper-and-server-state.md), [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md), [`architecture/protobuf-browser-transport-and-rest-gateway.md`](architecture/protobuf-browser-transport-and-rest-gateway.md)
- 브라우저 데이터: [`architecture/client-cache-and-storage.md`](architecture/client-cache-and-storage.md), [`architecture/browser-file-and-origin-storage.md`](architecture/browser-file-and-origin-storage.md), [`architecture/presigned-transfer-and-image-cdn.md`](architecture/presigned-transfer-and-image-cdn.md), [`architecture/server-file-capability-infrastructure.md`](architecture/server-file-capability-infrastructure.md)
- 실시간: [`architecture/realtime-events-web-push-and-bounded-polling.md`](architecture/realtime-events-web-push-and-bounded-polling.md)
- 디자인 시스템과 테스트 전략: [`styling/design-system-platform.md`](styling/design-system-platform.md), [`testing/frontend-platform-testing-strategy.md`](testing/frontend-platform-testing-strategy.md)
- 결정 기록(ADR): [`architecture/decisions/`](architecture/decisions/) `VD-*.md`
## 3. 작업 이력·리뷰
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 `README.md`의
"Files you can delete after copying" 절에 있다.
| 경로 | 내용 |
|---|---|
| [`superpowers/`](superpowers/) | 과거 작업 계획과 스펙 |
| [`reviews/`](reviews/) | 리뷰 결과와 리뷰 가이드. `reviews/adapters/INVENTORY.md`만 게이트가 읽는다. `reviews/adapters/`는 지우지 않는다: INVENTORY의 행과 `operations/adapter-remediation-ledger.md`가 그 안의 리뷰로 링크한다 |
| [`../SPEC.md`](../SPEC.md), [`../tasks/`](../tasks/) | 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 `docs/` 밖에 그대로 둔다 |