From 6ddb08e0b61545b0a950928ff56f62ac08e28027 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:07:58 +0900 Subject: [PATCH] docs: index docs/ by current contract, target design and history (14-05) Current contracts, target designs and work history shared one tree with no index. docs/README.md sorts them, names the files gates read, and marks the history folders; README lists what a copy can delete. SPEC.md and tasks/ stay in place because this round still uses them (D-16). Co-Authored-By: Claude Opus 5.5 --- README.md | 23 ++++++++++++++++ docs/README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 docs/README.md diff --git a/README.md b/README.md index b9b6444c..51ce9e84 100644 --- a/README.md +++ b/README.md @@ -184,6 +184,29 @@ project-owned integrations. They are target designs and review findings; a capability is not treated as implemented until its branch acceptance criteria and executable gates pass. +## Documentation + +[`docs/README.md`](docs/README.md) sorts the documents into current contracts, +target designs and work history. + +### Files you can delete after copying + +These record how the template was built. Nothing in the build or the gates +reads them, except the one file noted below. + +| Path | Contents | +| --- | --- | +| `docs/superpowers/` | past plans and specs | +| `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/INVENTORY.md`: `check:adapter-inventory` (FE-GATE-010) reads it | +| `SPEC.md`, `tasks/` | requirements and task list of the 2026-09-25 review fix round | +| `CLAUDE.md` | review instructions for the template repository itself; replace it with your own | + +The reference feature is not in this list: deleting its directory alone +leaves tests, policy entries and CI scripts behind that fail the gates. +`scripts/test-sample-removal.ts` removes it from a copy of +the repository and lists everything that has to go with it (its header comment +and `SAMPLE_EXTRAS`); do the same in your project and run the gates. + ## Verification Common local checks: diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..79e6fa37 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,72 @@ +# 문서 색인 + +`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) | 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 | + +입구 문서가 가리키는 세부 규칙: + +- 계약 소유와 호환성: [`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) + +게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다. + +| 파일 | 읽는 명령 | +|---|---| +| `architecture/review-ledger.json`, `architecture/review-evidence.md`, `accessibility/manual-checklist.md` | `verify:documentation` (FE-GATE-017) | +| `reviews/adapters/INVENTORY.md` | `check:adapter-inventory` (FE-GATE-010) | +| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` | + +## 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`만 게이트가 읽는다 | +| [`../SPEC.md`](../SPEC.md), [`../tasks/`](../tasks/) | 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 `docs/` 밖에 그대로 둔다 |