Files
clean-architecture-frontend…/docs/README.md
T
DongHyeonka 7a9aefdf25 feat(docs): 문서 체계 검사를 verify:documentation에 더하고 입구 문서를 고친다
문제: 프론트 문서 체계는 백엔드와 다르다. docs/README.md는 "README와
입구 문서는 영어"라고 정해 두어 2026-11-07 소유자 결정(살아 있는
문서는 본문까지 한국어)과 반대이고, 기록의 머리 블록·언어·숫자 복사를
보는 검사가 없다. verify:documentation은 docs/README.md 1절이 링크한
문서의 경로만 본다.

고른 방법: 백엔드 scripts/check-docs.py의 규칙(language, head, number,
map, readme, style)을 같은 이름·문턱으로 TypeScript로 옮겨
scripts/lib/docs-system.ts에 두고 verify:documentation(FE-GATE-017)이
부르게 한다. 참조 검사는 지금 있는 것을 그대로 쓰고 대상만 살아 있는
문서 전부로 넓힌다. FE-GATE-017 job은 workflow_dispatch(documentation
단계)에서만 돌아서, PR에서 실패하도록 merge 단계 FE-GATE-005의
documentation-readiness 시험이 이 repo를 그대로 두고
verify:documentation을 한 번 돌린다.
- 버린 안: 새 게이트나 package script를 더하는 것. config/ci(정리
  3단계·CI 세션 범위)와 CI 계약의 개수·해시를 건드린다.
- 버린 안: check-docs.py를 그대로 복사하는 것. 프론트 CI 이미지와
  도구는 Node뿐이고, 참조 검사(짝 백엔드 pin, 지운 샘플, 생성 산출물)는
  이미 TS에 있다.
- 예외 목록 scripts/docs-system-exceptions.txt는 줄기만 한다(줄마다
  FROZEN 지문). 이 커밋의 줄은 아직 옮기지 않은 문서의 기준선이고 뒤
  번역 커밋들이 지운다.
- docs/README.md를 모든 문서 폴더를 덮는 지도와 수명·언어·머리 블록·
  검사 규칙으로 다시 쓰고, 루트 README.md를 docs-system.md 6.1절의 필수
  절 순서로 한국어로 다시 쓴다. README의 src 폴더 설명은 layers.md 표와
  글자가 같아야 하므로 layers.md·overview.md·foundation.md를 같이 옮긴다.
- README 「복사한 뒤 지워도 되는 것」을 읽는 정규식과, 문서를 바꿔 넣는
  테스트의 기대 문자열을 새 한국어 문장으로 고친다. 검사기는 기록
  폴더 이름을 적지만 지운 사본에서도 통과하므로
  deletable-history-documents 테스트의 검사 대상에서 뺀다(그 이유를
  테스트와 검사기 시험에 적었다).

위험: 파생 서비스가 이 변경을 받으면 자기 살아 있는 문서가 영어일 때
verify:documentation이 실패한다. CHANGELOG에 「먼저 할 일」로 적는다.
review-evidence.md는 다른 작업 공간의 경로를 적은 사본이라 참조·숫자
검사에서 뺐다(HISTORY_HOLDERS).

검증: tests/unit/docs-system.test.ts(조건마다 실패 입력),
documentation-readiness·template-feature-removal-documents·
deletable-history-documents 시험, verify:documentation을 desktop에서 돌렸다.
2026-11-08 21:57:39 +09:00

180 lines
16 KiB
Markdown

# docs
저장소의 문서는 이 폴더 아래에 있다(루트 `README.md`, `CHANGELOG.md` 등 몇 개는 밖에 있다). 이 README는 두 가지를 정한다.
- 어떤 문서가 어느 폴더에 있나: 1절 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
- 문서의 수명에 따라 무엇을 어떤 언어로 어떻게 고치나: 2절부터.
규칙의 정본은 design-docs 저장소의 `conventions/docs-system.md`다. 이 README는 그 규칙을 이 repo에 적용한 내용이고, 이 템플릿을 복사한 프로젝트도 이 README를 따른다.
파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.
문서와 코드가 다르면 코드가 맞다.
## 1. 문서 지도
- 표의 첫 칸이 폴더다(`docs/` 기준 경로).
- 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
- 문서 검사의 `map`이 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(5절).
### 처음 읽을 문서
| 문서 | 정하는 것 |
| --- | --- |
| [`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) | 기본 라우트, 인증 모드, 기능 추가·제거 절차 |
| [`manual/`](manual/README.md) | 새 기능을 더하는 순서와 판단 기준, `create:feature`, 완료 기준([`manual/reference/`](manual/reference/)) |
| [`operations/ci-quality-gates.md`](operations/ci-quality-gates.md), [`testing/taxonomy.md`](testing/taxonomy.md) | 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
### 매뉴얼
일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.
| 폴더 | 무엇 |
| --- | --- |
| `manual/` | 개발 매뉴얼: 새 기능 하나를 더하는 0~11단계, 결정표, 기능 폴더 밖 파일, 짝 백엔드에 붙이기. `manual/reference/`에 명령 인자, 전역 ID, 패턴, 오류 메시지, 완료 기준 |
### 현재 계약
지금 코드가 지키는 규칙이다. 코드와 같은 변경에서 고친다.
| 폴더 | 무엇 |
| --- | --- |
| `architecture/` | 계층과 import 규칙(`architecture/layers.md`), 플랫폼의 역할, 스타터, recipe 절차, 정적 배포, 계약 소유, 규모 설계(`architecture/scale-architecture.md`, 코드 주석의 `scale-architecture.md §N`이 가리킨다), 짝 백엔드 계약(`architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1절이 실행 규칙. 기준 커밋은 `config/contracts/backend-contract-pin.json`), 2026-07-18 도식 리뷰 기록의 사본(`architecture/review-evidence.md`, `architecture/review-ledger.json`) |
| `contracts/` | 계약 호환 규칙(읽는 쪽을 먼저 배포한다) |
| `security/` | 브라우저 보안 경계와 공급망 |
| `styling/` | 디자인 토큰 |
| `accessibility/` | 수동 접근성 검토 체크리스트. 라우트별 기록은 repo 루트의 `artifacts/tests/a11y-manual/`에 있다 |
| `testing/` | 테스트 계층(taxonomy)과 새 프로젝트가 초기화할 기준선 |
### 운영
| 폴더 | 무엇 |
| --- | --- |
| `operations/` | CI 품질 게이트, capability별 복구 절차, 릴리스·캐시 롤백, 성능 증거, 2026-08-14 adapter 재검토의 처리 원장(`operations/adapter-remediation-ledger.md`) |
| `runbooks/` | 오류 code별 장애 대응 runbook(`FE-RB-00N`). 등록은 `config/runbooks/runbooks.json` |
### 결정 기록
| 폴더 | 무엇 |
| --- | --- |
| `adr/` | 결정 기록(VD). 번호는 옮기기 전과 같다(`VD-NN-<주제>.md`). 2026-11-08에 architecture 아래 decisions 폴더에서 옮겼다 |
### 설계와 기록
설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.
| 폴더 | 무엇 |
| --- | --- |
| `design/` | 설계서. `YYYY-MM-DD-<주제>-design.md`. 2026-11-08에 옛 superpowers 폴더의 specs와 `architecture/`의 목표 설계를 옮겼다 |
| `history/plans/` | 계획서. 2026-09-25 리뷰 수정 라운드의 요구사항(`SPEC.md`)과 작업 목록도 여기 있다 |
| `history/evidence/` | 작업 단계의 증거·체크포인트 |
| `reviews/` | 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나. 리뷰 가이드와 실행 체크리스트는 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 둘이 있다 |
- 계획서 본문에는 그때 계획한 경로와 명령이 그대로 남아 있다. 계획서를 나중에 고치지 않는 이유는, 고치면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 되기 때문이다.
- `history/`와 `reviews/`는 복사한 프로젝트가 지워도 된다(루트 `README.md` 「복사한 뒤 지워도 되는 것」). 예외는 `reviews/adapters/`다: `reviews/adapters/INVENTORY.md`는 `check:adapter-inventory`(FE-GATE-010)가 `src/adapters`와 대조하는 살아 있는 목록이다.
- `design/`과 `adr/`은 코드 주석이 근거로 가리키므로 지우지 않는다.
### 폴더 밖 문서
| 문서 | 무엇 |
| --- | --- |
| [`../README.md`](../README.md) | 루트 README. 6절의 필수 절을 가진다 |
| [`../CHANGELOG.md`](../CHANGELOG.md) | 템플릿 버전 사이의 변경. 지난 상태를 적는 문서라 문서 검사의 참조·숫자 검사는 보지 않는다 |
| [`../CLAUDE.md`](../CLAUDE.md) | 이 repo를 리뷰할 때의 기준 |
| [`../PRODUCT.md`](../PRODUCT.md) | 디자인 도구가 읽는 제품 맥락 |
| [`../src/adapters/browser-transfer/image-cdn/README.md`](../src/adapters/browser-transfer/image-cdn/README.md) | Image CDN adapter의 모듈 README |
### 게이트가 읽는 파일
지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
| --- | --- |
| 이 파일, `architecture/review-ledger.json`, `architecture/review-evidence.md` | `verify:documentation` (FE-GATE-017) |
| repo 루트의 라우트별 수동 접근성 기록(`artifacts/tests/a11y-manual/<ROUTE_ID>.md`) | `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`) |
| `architecture/backend-api-and-server-state-contract.md` 6.1절 표 | `tests/unit/backend-contract-pin-document.test.ts` (FE-GATE-005) |
| `architecture/starter-experience.md`의 기능 폴더 밖 파일 표, `manual/03-outside-feature-folder.md` A절 | `tests/unit/feature-tracked-files.test.ts` (FE-GATE-005) |
| `manual/`의 표시한 코드 블록과 `manual/04-paired-backend-session.md` 3.2절 | `tests/unit/manual-code-blocks.test.ts`, `tests/unit/manual-paired-backend-settings.test.ts` (FE-GATE-005) |
## 2. 문서 수명과 언어
| 수명 | 문서 | 위치 | 언어 | 고치는 법 |
| --- | --- | --- | --- | --- |
| 살아 있음 | README, `CLAUDE.md`, 매뉴얼(`manual/`), 현재 계약(`architecture/`, `contracts/`, `security/`, `styling/`, `accessibility/`, `testing/`), 운영(`operations/`, `runbooks/`), `reviews/adapters/INVENTORY.md`, 모듈 README, `CHANGELOG.md` | 제자리 | 한국어 | 코드와 같은 변경에서 고친다(4절) |
| 결정 | 결정 기록(VD) | `adr/` | 한국어 | 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 맨 아래에 날짜가 있는 「보완」 절을 덧붙인다. 크게 바뀌면 새 VD를 쓰고 옛 VD를 「대체됨」으로 한다 |
| 기록 | 설계서, 계획서, 증거, 리뷰 | `design/`, `history/`, `reviews/` | 머리 블록은 한국어, 본문은 쓴 때의 원문 | 머리 블록의 칸만 고친다 |
- 살아 있는 문서와 결정 기록의 본문은 한국어로 쓴다. 설정 파일의 사람이 읽는 설명 칸(recipe 카탈로그, runbook 등록)도 한국어다.
- 원문으로 두는 것: 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 외부 문서 인용, 제품 이름.
- 용어는 자연스러운 한국어 → 한국어(영어) → 영어 그대로 순으로 고른다. 처음 나올 때 한 번 병기한다. 이 repo가 영어로 쓰는 말(adapter, port, capability, recipe, feature, context, slice, registry, gate 등)은 영어로 둔다.
- 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
- 2026-11-08에 살아 있는 문서를 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(5절).
- `artifacts/tests/a11y-manual/`의 라우트별 기록은 문서가 아니라 정해진 영어 키 형식의 게이트 입력이다(`scripts/lib/manual-a11y-evidence.ts`). 문서 검사가 보지 않는다.
## 3. 기록 문서의 머리 블록
`design/`, `history/`, `adr/`의 `.md` 파일은 맨 위에 이 블록을 둔다. 블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).
```text
<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 구현됨
- 작성일: 2026-08-01
- 요약: 한국어 한 문장
- 현재 정본: `docs/architecture/layers.md`
- 대체됨: `docs/design/<대체한 문서>.md`
<!-- 머리 블록 끝 -->
```
- 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: `design/` 설계서, `history/plans/` 계획서, `history/evidence/` 증거. 결정 기록(`adr/`)의 둘째 줄은 `> **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.`다. VD는 처음부터 한국어로 썼고 번역하지 않았다. 나중에 본문을 번역하면 「원문이다」 대신 「내용이다(번역은 뜻을 바꾸지 않았다)」로 쓴다.
- 상태는 종류마다 고정 어휘다.
| 종류 | 상태 |
| --- | --- |
| 설계서 | 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함 |
| 결정 기록 | 제안 · 채택 · 채택(보완) · 폐기 · 대체됨 |
| 계획서 | 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함 |
| 증거 | 보관 |
- 「현재 정본」은 지금 동작을 설명하는 살아 있는 문서나 코드의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.
- 「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.
- 상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다. 새 설계서·결정 기록은 처음부터 블록을 달고 쓴다(보통 「제안」).
- 2026-11-08에 처음 단 상태는 원래 상태 줄을 기계로 바꾼 값이다: Accepted·Approved·확정·승인·정본 → 채택, Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 날짜가 붙은 보완 메모가 본문에 있는 VD → 채택(보완). 상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.
- `.md`가 아닌 파일(레인 준비 셸 스크립트)에는 달지 않는다. 같은 폴더 문서의 블록이 그 파일을 설명한다.
- 리뷰(`reviews/`)는 아직 머리 블록을 요구하지 않는다.
## 4. 문서와 코드를 같은 변경에서 고친다
- 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법: `git grep -n '<바꾼 이름>' -- '*.md'`.
- 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·명령은 `CHANGELOG.md`에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 `> 이력` 으로 시작하는 인용 블록 안에 쓴다. 문서 검사는 그 블록의 문체를 보지 않는다.
- 숫자·버전을 복사하지 않는다. 프레임워크 버전은 `package.json`과 `.nvmrc`, 게이트 목록은 `config/ci/gates.json`, recipe 목록은 `config/recipes/frontend-capability-recipes.json`, adapter 파일 목록은 `reviews/adapters/INVENTORY.md`를 가리킨다.
- 루트 README는 「프로젝트 구조」와 「문서 지도」 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs `conventions/docs-system.md` 6.1절이고, 문서 검사의 `readme`가 그 목록(`scripts/lib/docs-system.ts`의 `README_SECTIONS`)을 본다.
## 5. 문서 검사
`verify:documentation`(FE-GATE-017)이 위 규칙 중 기계로 볼 수 있는 것을 본다. 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 script를 지우는 변경이 그 변경과 상관없는 문서를 낡게 만든다.
- pull request에서 실패하게 하는 곳은 merge 단계 FE-GATE-005다. 그 안의 `tests/unit/documentation-readiness.test.ts`가 이 repo를 그대로 두고 `verify:documentation`을 한 번 돌린다. FE-GATE-017 job 자체는 documentation 단계를 고른 workflow_dispatch에서만 돈다(`config/ci/gates.json`의 `documentation_gate`).
| 검사 | 보는 것 |
| --- | --- |
| `language` | 살아 있는 문서와 결정 기록 본문이 한국어인가. 코드·명령·경로·링크·인용은 세지 않고, 영어 낱말 3개 이상이면서 한글 덩어리 비율 0.3 미만이면 영어다(보고 언어 훅 H11과 같은 판정) |
| `head` | 기록과 결정 기록 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 지금 있는지 |
| `document references` | 살아 있는 문서의 인라인 코드·셸 코드 블록 안 repo 경로, 마크다운 링크 대상, package script 이름, FE-GATE ID가 지금 있는가. 짝 백엔드 경로는 `config/contracts/backend-contract-pin.json`이 고정한 커밋의 트리에서 찾는다 |
| `number` | 살아 있는 문서가 프레임워크 버전이나 게이트·recipe·adapter 개수를 복사했는가. 결정 기록, 기록, `CHANGELOG.md`는 보지 않는다 |
| `map` | 이 README의 1절 지도가 `docs/` 아래 모든 폴더를 덮는가(표 첫 칸의 `폴더/`). 파일 없이 폴더만 가진 묶음 폴더(`history/`)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다 |
| `readme` | 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 `##` 절을 정해진 순서로 가지는가 |
| `style` | 살아 있는 문서와 결정 기록의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안 인용, `> 이력` 블록은 보지 않는다 |
- 그 밖에 같은 명령이 루트 README의 런타임 변수 표, 입구 문서의 `src/` 폴더 설명(`architecture/layers.md` 표와 글자가 같아야 한다), 수동 접근성 기록의 범위, 2026-07-18 도식 리뷰 사본 둘의 일치를 본다.
- 규칙과 판정의 정본은 `scripts/lib/docs-system.ts`(검사 여섯)와 `scripts/verify-documentation-readiness.ts`(참조와 그 밖의 검사)다. 백엔드 템플릿의 문서 검사기(그 repo의 `check-docs.py`)를 같은 이름·문턱으로 옮긴 것이다.
- 검사 자신의 시험: `tests/unit/docs-system.test.ts`, `tests/unit/documentation-readiness.test.ts`.
- 예외 목록 `scripts/docs-system-exceptions.txt`는 비어 있고 줄기만 한다. 목록에 새 줄을 더하면 실패한다(줄마다 `scripts/lib/docs-system.ts`의 `FROZEN`에 지문이 있어야 하는데, `FROZEN`이 비어 있다). 기준선을 늘리는 것은 규칙을 바꾸는 일이라 소유자 결정이 필요하다.
- 복사한 프로젝트가 지운 기록(`history/`, `reviews/`)과 지운 샘플 기능의 경로는 없어도 된다. git이 무시하는 생성 산출물도 없어도 된다.
- 설명·수치가 코드와 맞는지는 검사하지 않는다. 리뷰가 표본으로 대조한다.