diff --git a/.claude/rules/docs.md b/.claude/rules/docs.md index 8c4205ec..8e422031 100644 --- a/.claude/rules/docs.md +++ b/.claude/rules/docs.md @@ -5,11 +5,11 @@ paths: # 문서를 고칠 때 -- 문서 위치·묶음·언어 규칙은 `docs/README.md`, 쓰는 절차는 `docs/work/docs-writing.md`다. -- 기록 문서(`docs/reviews/`, `docs/history/`, `docs/superpowers/`, 결정 기록)는 머리 블록만 고친다. 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 예외는 그 라운드를 맡은 총괄이 리뷰 README에 「조치」 절(과 그 아래 diff 리뷰 절)을 더하는 것이다. +- 문서 위치·수명·언어 규칙은 `docs/README.md`, 쓰는 절차는 `docs/work/docs-writing.md`다. 살아 있는 문서는 본문까지 한국어로, 「~한다」체로 쓴다. +- 기록 문서(`docs/reviews/`, `docs/history/`, `docs/design/`, 결정 기록 `docs/adr/`)는 머리 블록만 고친다. 리뷰 영역 문서를 리뷰 뒤에 고치지 않는다. 예외는 그 라운드를 맡은 총괄이 리뷰 README에 「조치」 절(과 그 아래 diff 리뷰 절)을 더하는 것이다. - 진입 문서(루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/` 아래 문서) 본문에는 지난 리뷰 ID·번호만 쓴 결정을 넣지 않는다. 내용과 날짜를 쓰고 ID는 `docs/work/evidence.md`로 옮긴다. 편집 훅이 `scripts/check-work-docs.py`의 실패 줄을 먼저 알려 준다. -- `docs/README.md` 1절이 링크한 문서(루트 `AGENTS.md`, `docs/work/` 포함)는 `verify:documentation`이 백틱 경로·명령 경로·마크다운 링크·package script·FE-GATE ID를 본다. 있는 것만 쓴다. 검사를 피하려고 백틱을 빼지 않는다. 기능 제거 드릴의 문서 사본은 `scripts/lib/removal-fixture.ts`의 목록만 복사하니, 그 목록 밖 루트 파일을 마크다운 링크로 가리키지 않는다. +- 살아 있는 문서 전부(루트 `AGENTS.md`, `docs/work/`, `.claude/` 아래 문서 포함)를 `verify:documentation`이 본다: 언어·문체·숫자 복사와 백틱 경로·명령 경로·마크다운 링크·package script·FE-GATE ID. 있는 것만 쓴다. 검사를 피하려고 백틱을 빼지 않는다. 기능 제거 드릴의 문서 사본은 `scripts/lib/removal-fixture.ts`의 목록만 복사하니, 그 목록 밖 루트 파일을 마크다운 링크로 가리키지 않는다. - repo 밖 문서(design-docs 등)는 링크가 아니라 코드 표기로 쓴다. - 숫자(예산, 기준선, 테스트 수)를 옮겨 적지 않는다. 정본을 가리킨다. - 그 문서를 읽는 테스트를 `git grep -n '<파일 이름>' -- tests scripts`로 찾는다. 있으면 desktop에서 돌린다. -- 고친 뒤: 작업 매뉴얼이면 `scripts/verify.sh docs`(노트북), 1절 묶음이면 desktop `scripts/verify.sh script verify:documentation`. +- 고친 뒤: 작업 매뉴얼이면 `scripts/verify.sh docs`(노트북), 그리고 살아 있는 문서를 바꿨으면 desktop `scripts/verify.sh script verify:documentation`. diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index e3dab6e9..81abe1f7 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -24,7 +24,7 @@ }, { "name": "presentation-does-not-know-adapters", - "comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/architecture/frontend-ports-adapters-and-boundaries.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.", + "comment": "§4. Presentation talks to application ports, not concrete adapters, the composition root or the TanStack runtime. Exception: src/presentation/adapters/query is the TanStack Query binding, the one place @tanstack is imported (docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md). It needs @tanstack only; concrete-adapters-compose-only-in-bootstrap still keeps it off src/adapters. Owner: frontend-platform. Revisit if the binding moves out of presentation.", "severity": "error", "from": { "path": "^src/presentation/(?!adapters/query)" diff --git a/.env.example b/.env.example index 80f19b81..8a0ea0a0 100644 --- a/.env.example +++ b/.env.example @@ -8,7 +8,7 @@ # materialized into `dist/config.json` at build time. Only the emergency # switches (CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) may be changed in a # deployed config.json without rebuilding, by the checked procedure in -# docs/runbooks/FE-RB-001.md. See the "Runtime configuration" section of +# docs/runbooks/FE-RB-001.md. See the 「런타임 설정과 배포 변수」 section of # README.md. # # Copy to `.env.local` (git-ignored) to override locally. diff --git a/CHANGELOG.md b/CHANGELOG.md index 223749b8..ad0075ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ # 변경 이력 이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다. -가져오는 방법은 `README.md`의 "Updating a copied project" 절에 있다. +가져오는 방법은 `README.md`의 「원본 업데이트 반영」 절에 있다. - 버전은 git 태그 `vX.Y.Z`로 식별한다. 태그 사이의 변경을 여기 적는다. - 미출시 절은 한 번의 동기화 단위(기준 커밋 → 브랜치 끝)에서 받는 변경의 순 요약이다. 최종 상태만 적고, 같은 범위 안에서 뒤 커밋이 바꾼 중간 상태는 지운다. 호환을 깨는 변경은 절 첫머리 "먼저 할 일"에 옮기기 전·옮기는 법·옮긴 뒤 확인 순서로 적는다. @@ -43,7 +43,7 @@ ## 미출시 — `48c7695b` → 정리 단계 -2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지)을 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다. +2026-11-07 소유자가 지시한 저장소 정리다(design-docs `repo-structure/04-frontend-layout.md` 9.2절, 결정은 `repo-structure/README.md` 3.4절). 범위는 `main` `48c7695b`(PR #9 병합) 다음부터다. 1단계(PR #11, `85f941c4`~`121e1125`, `main` `f33e4778`에 합침), 2단계(브랜치 `chore/layout-2-sample-removal`, `c7e80f2f`~`ad3a071f`), 3단계(합치기)와 4단계(배치 규칙 검사)(브랜치 `chore/layout-3-merge`, `bf485f44`~`c54c3813`), CI 재편(브랜치 `chore/ci-merge-jobs`, `0739f26b`부터 브랜치 끝까지), 문서 체계 단계(브랜치 `claude/fe-b-docs-korean-645f55`, `99e76e87`부터 브랜치 끝까지. design-docs `conventions/docs-system.md`)를 담는다. 기준점 `48c7695b`를 빼면 이 절의 해시는 모두 이 범위에 있다. ### 먼저 할 일 (BREAKING) @@ -52,6 +52,7 @@ #### 옮기기 전 - 템플릿은 참조 기능(`src/features/reference-feature/`, context `src/contexts/reference-context/`)과 예제 화면(`src/features/platform-examples-feature/`, context `src/contexts/platform-examples-context/`)을 지웠다. 받으면 템플릿 쪽 파일의 삭제가 함께 온다. +- 자기 문서가 템플릿 문서의 옛 경로(`docs/superpowers/`, `docs/architecture/decisions/`, `docs/architecture/`의 목표 설계, 루트 `SPEC.md`)를 가리키는지 본다: `git grep -n -E 'docs/superpowers|architecture/decisions|SPEC\.md' -- '*.md' src tests scripts`. 새 위치는 아래 표의 문서 이동 행에 있다. - 자기 프로젝트가 그 폴더를 고쳐 남겨 두었는지 본다: `git log --oneline <마지막 동기화 기준>..HEAD -- src/features/reference-feature tests/features/reference-feature src/features/platform-examples-feature`. 고친 파일은 병합에서 수정/삭제 충돌이 된다. #### 옮기는 법 @@ -71,6 +72,9 @@ 13. **CI 계약 기준선 파일이 없어졌다.** `config/ci/contract-baseline.json`, `scripts/update-ci-contract-baseline.ts`, `update:ci-contract-baseline` script를 지웠다(소유자 결정). 위 12단계와 이 절 4단계, 아래 절들의 "기준선을 다시 기록한다"는 이 절까지 받으면 할 일이 없다. 병합에서 자기 기준선 파일이 수정/삭제 충돌이 되면 삭제 쪽을 고른다. 자기 script나 문서가 `update:ci-contract-baseline`을 부르면 지운다 (`f6b2b96c`) 14. **merge 단계 job 이름이 바뀌었다.** 게이트마다 하나이던 행렬 job(`FE-GATE-NNN / <이름>`)이 `merge / static checks`(`merge_static`), `merge / tests`(`merge_test`), `merge / browser tests`(`merge_browser`) 셋이 됐다. 게이트는 job 안의 단계 이름(`FE-GATE-NNN / <이름>`)으로 남는다. Gitea 브랜치 보호의 필수 검사를 옛 job 이름으로 걸었으면 새 job 셋으로 바꾼다. 증거 업로드 이름도 `FE-GATE-NNN-`에서 `merge-static-`·`merge-test-`·`merge-browser-`으로 바뀌었다 (`0739f26b`) +7. **자기 문서를 새 문서 검사에 맞춘다.** `verify:documentation`(FE-GATE-017)이 살아 있는 문서 전부(루트 `README.md`, `docs/` 아래 기록 밖 문서, 모듈 README)를 본다: 본문이 한국어인지, 「~한다」 체인지, 버전·개수를 복사하지 않았는지, 적은 경로·script·게이트 ID가 있는지. 루트 README는 `## 프로젝트 구조`부터 `## 규칙과 기여`까지 정해진 절을 순서대로 가져야 하고, `docs/README.md`는 `docs/` 아래 모든 폴더를 표 첫 칸 `폴더/`로 덮어야 한다. 자기 기록(`docs/design/`, `docs/history/`, `docs/adr/`)은 맨 위에 머리 블록을 단다(형식은 템플릿 `docs/README.md` 3절). 한 번에 다 고칠 수 없으면 걸린 줄을 `scripts/docs-system-exceptions.txt`에 기준선으로 적고 그 지문을 `scripts/lib/docs-system.ts`의 `FROZEN`에 넣는다. 그 목록은 줄기만 한다 (`7a9aefdf`) +8. **README의 바뀐 절 이름을 따른다.** 「Files you can delete after copying」은 「복사한 뒤 지워도 되는 것」이다. `verify:documentation`이 이 제목 아래 표의 첫 칸으로 지워도 되는 경로를 읽는다. 자기 README를 템플릿 README로 받았으면 이 제목을 지킨다 (`7a9aefdf`) + #### 옮긴 뒤 확인 1. 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것: `check:registries`(3단계), `check:ci`(4·12단계), `test:unit`(5·9·11단계), `generate:feature-index`(6단계), `check:types`·`check:types:fixtures`(7·8단계), `verify:documentation`(지운 샘플 경로를 적은 자기 문서, 9단계, 매뉴얼 03 E절 R6·R7), `test:sample-removal`(인자 없이 돌면 목록이 빈 템플릿에서는 `SKIP`을 출력한다). @@ -94,6 +98,9 @@ | [계약] | 저장소 배치 규칙 R1~R10을 매뉴얼 03 E절에 적고, 기계로 볼 수 있는 것을 게이트에 넣었다: R1·R2·R7(파일)·R9 `tests/unit/repository-layout.test.ts`, R3 `tests/unit/tracked-artifacts.test.ts`, R4·R5 `tests/unit/example-feature-rules.test.ts`(이상 FE-GATE-005), R6·R7(문서) `verify:documentation`(FE-GATE-017, 산출물에 `layoutRuleViolations`), R8 FE-GATE-003 | `docs/manual/03-outside-feature-folder.md`, `scripts/verify-documentation-readiness.ts`, `scripts/contracts/release-artifacts.ts` | `e902e657` | | [계약] **BREAKING** | merge 단계 job 14개(게이트마다 행렬 하나)를 셋으로 합쳤다. job마다 설치를 한 번 하고 게이트를 차례로 돈다. 앞 게이트가 실패해도 다음 게이트가 돈다(`if: ${{ !cancelled() }}`). release 단계는 세 job을 모두 기다린다. 위 "먼저 할 일" 14 | `config/ci/gates.json` `jobs`, `scripts/contracts/ci-gates.ts`, `scripts/generate-ci-workflow.ts`, `.gitea/workflows/quality-gates.yml` | `0739f26b` | | [계약] **BREAKING** | 새 단계 `main`(`MAIN_READY`, 승격을 막지 않음)과 게이트 FE-GATE-029 `checker-self-tests`. FE-GATE-001·005·008·010·013의 `*:fixture` 명령 15개와 그 증거, `check:ci`의 ungated 검사(`check:ci:gating`으로 뗌)를 옮겼다. merge 단계 명령 참조 64 → 49. 음성 타입 fixture(`check:types:fixtures`)는 src 타입 계약 시험이라 merge에 남겼다. CI 계약 기준선 파일은 지웠다. 위 "먼저 할 일" 13 | `config/ci/gates.json`, `scripts/check-ci-gating.ts`, `scripts/lib/promotion-readiness.ts` | `f6b2b96c` | +| [계약] **BREAKING** | 문서 체계 검사가 생겼다. `verify:documentation`이 백엔드 `check-docs.py`와 같은 규칙 여섯(language, head, number, map, readme, style)을 `scripts/lib/docs-system.ts`로 돌리고, 참조 검사의 대상이 `docs/README.md` 1절이 링크한 문서에서 살아 있는 문서 전부로 넓어졌다. pull request에서는 FE-GATE-005의 `tests/unit/documentation-readiness.test.ts`가 이 repo로 `verify:documentation`을 돌리므로 문서가 걸리면 merge 단계가 실패한다. 예외 목록(`scripts/docs-system-exceptions.txt`)은 비어 있고 줄기만 한다. 위 "먼저 할 일" 7 | `scripts/lib/docs-system.ts`, `scripts/verify-documentation-readiness.ts`, `scripts/docs-system-exceptions.txt`, `docs/README.md` | `7a9aefdf` | +| [계약] | 문서를 수명으로 나눠 옮겼다. 설계서는 `docs/design/`(옛 `docs/superpowers/specs/`와 `docs/architecture/`의 목표 설계 16개는 `<작성일>-<이름>-design.md`로), 계획서는 `docs/history/plans/`(옛 `docs/superpowers/plans/`, 루트 `SPEC.md`는 `docs/history/plans/2026-09-25-review-fix-round/`), 결정 기록 VD는 `docs/adr/`(번호 그대로)다. 기록 67개에 한국어 머리 블록(상태·작성일·요약·현재 정본)을 달았다. 코드 주석의 문서 경로도 고쳤다. 위 "먼저 할 일" 옮기기 전 | `docs/design/`, `docs/history/`, `docs/adr/`, `.dependency-cruiser.json`, `tests/component/router.test.tsx` | `99e76e87`, `e632b230`, `9540bf81`, `75fad73a`, `2b8a348c` | +| [계약] | 루트 README를 한국어로 다시 썼다. 절은 프로젝트 구조 → 시작하기 → (런타임 설정과 배포 변수) → 기능 켜고 끄기 → 문서 지도 → 검증 → 새 서비스로 시작하기 → 규칙과 기여다. 옛 「Support scope」는 「기능 켜고 끄기」의 「지원 범위」, 「Updating a copied project」는 「새 서비스로 시작하기」의 「원본 업데이트 반영」, 「CI and evidence」는 「검증」의 「게이트와 CI」다. 위 "먼저 할 일" 8 | `README.md`, `tests/unit/documentation-readiness.test.ts` | `7a9aefdf` | ### 그 밖의 수정 @@ -105,6 +112,14 @@ - 기능 스위치 시험(`tests/component/product-feature-switch.test.tsx`)과 홈 시작 링크의 스위치 시험은 시험 전용 fixture 기능으로 옮겼다 (`e3c8db48`). - 라우트 런타임 음성 fixture(`tests/fixtures/typecheck/invalid-route-runtime.ts`)는 라우트 하나만 뺀다. 빠진 라우트 수에 따라 TS2739와 TS2740으로 갈리던 진단이 TS2741 하나가 됐고 FE-GATE-003의 기대 진단도 바꿨다. 라우트가 3개로 줄자 옛 기대(TS2740)가 어긋났다 (`e47a0ab2`). +- 살아 있는 문서를 모두 한국어로 옮겼다(현재 계약, 운영, runbook, 보안, 스타일, 접근성, 테스트, 모듈 README). 뜻은 바꾸지 않았고 백틱 안, 링크 대상, 절 번호, 표 구조는 그대로다. 문서를 읽는 테스트의 기대 문자열(`tests/unit/feature-tracked-files.test.ts`)과 절 이름을 인용한 주석을 같이 고쳤다 (`af10cae9`, `45e8cb77`, `11530b1a`). +- `check:remediation-ledger`는 옮긴 원장의 절 제목 `## 세 번째 재검토 (2026-08-14)`을 찾고, 「모두 닫혔다」를 한국어로도 잡는다 (`45e8cb77`). +- 하네스 범위가 더한 작업 매뉴얼·규칙(`docs/work/`, `.claude/rules/docs.md`, `docs/problem-statement.md`)의 문서 체계 설명을 새 위치와 검사 범위(살아 있는 문서 전부)에 맞췄다. `docs/work/evidence.md`는 근거 기록이라 참조·숫자 검사에서 뺐다 (`5757742e`). +- `verify:documentation`의 경로 검사가 줄임표 「…」를 `...`처럼 자리표시자로 본다(`node scripts/…`). 문서가 제거 드릴 사본에 없는 루트 파일을 링크하지 않게 `docs/README.md`를 고쳤다. 문서 검사를 띄우는 시험에 60초 한도를 줬다 (`743f6fcc`, `5f10f928`, `7b09c215`). +- 문서 검사는 라우트별 수동 접근성 기록(`docs/accessibility/route-reviews/`)을 문서로 보지 않는다. 정해진 영어 키 형식의 게이트 입력이다 (`e9e98b8a`). +- `SPEC.md`의 공통 완료 기준은 하네스 범위가 `docs/work/improve.md` 5절로 옮겼다. 이 범위가 먼저 만든 사본 `docs/manual/reference/done-criteria.md`는 지웠다(`ee5e19f4`에서 만들고 뒤 커밋에서 지움). +- 설정 파일의 설명 칸(recipe 카탈로그, runbook 등록, 규모 상한, 짝 백엔드 pin의 `fact`, secret scan 허용 이유)을 한국어로 옮겼다. 키와 값의 모양은 그대로다 (`309631e4`). + ### 알려진 제한 - 두 다운스트림에 시험 병합을 하지 않아 충돌 수를 모른다(S4 가정 F4). diff --git a/PRODUCT.md b/PRODUCT.md index d6263b02..f18b63e3 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -8,49 +8,49 @@ web ## Users -- **템플릿을 가져다 쓰는 개발자**: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람입니다. 기본 화면(홈, 플랫폼 구성)과 Storybook 갤러리(UI 구성요소, 화면 상태)는 이 사람이 실행 구조와 공통 동작을 확인하는 용도입니다. -- **파생 서비스의 최종 사용자**: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로 쓰는 사람을 기준으로 합니다. +- **템플릿을 가져다 쓰는 개발자**: 이 템플릿으로 새 서비스를 빠르게 시작하는 사람이다. 기본 화면(홈, 플랫폼 구성)과 Storybook 갤러리(UI 구성요소, 화면 상태)는 이 사람이 실행 구조와 공통 동작을 확인하는 용도다. +- **파생 서비스의 최종 사용자**: 디자인 시스템(토큰, 프리미티브, 패턴, 레이아웃, 페이지 템플릿)은 이 템플릿으로 만든 서비스를 실제로 쓰는 사람을 기준으로 한다. ## Product Purpose -도메인·비즈니스·DB 로직을 뺀 공통 기능을 모두 갖춘 React/Vite 프론트엔드 출발점입니다. 아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약으로 둡니다. 성공 기준은 이 템플릿에서 도메인만 추가해 서비스를 빠르게 만들고, 운영 중인 desktop 서버에 바로 띄워 출시할 수 있는 것입니다. +도메인·비즈니스·DB 로직을 뺀 공통 기능을 모두 갖춘 React/Vite 프론트엔드 출발점이다. 아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약으로 둔다. 성공 기준은 이 템플릿에서 도메인만 추가해 서비스를 빠르게 만들고, 운영 중인 desktop 서버에 바로 띄워 출시할 수 있는 것이다. ## Positioning -화면 품질 규칙(접근성, 상태 표현, 반응형, 토큰 사용)이 문서가 아니라 게이트로 강제됩니다. 시각 회귀 골든, 아키텍처 검사, 접근성 테스트가 그 게이트입니다. 그래서 파생 서비스가 템플릿을 고쳐도 기준이 조용히 낮아지지 않습니다. +화면 품질 규칙(접근성, 상태 표현, 반응형, 토큰 사용)이 문서가 아니라 게이트로 강제한다. 시각 회귀 골든, 아키텍처 검사, 접근성 테스트가 그 게이트다. 그래서 파생 서비스가 템플릿을 고쳐도 기준이 조용히 낮아지지 않는다. ## Operating Context -- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker입니다. SSR은 없습니다. -- 파생 서비스는 운영 중인 desktop 서버에 배포됩니다. -- 예제 앱 셸에는 테마 전환(시스템/라이트/다크), 언어 전환(한국어/영어), 로그인 상태 표시가 있습니다. +- 실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다. SSR은 없다. +- 파생 서비스는 운영 중인 desktop 서버에 배포된다. +- 예제 앱 셸에는 테마 전환(시스템/라이트/다크), 언어 전환(한국어/영어), 로그인 상태 표시가 있다. ## Capabilities and Constraints -- 하나의 디자인 시스템으로 세 종류의 서비스를 받칩니다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩 페이지입니다. -- 디자인 시스템 위치는 `src/presentation/design-system/`입니다. 토큰은 primitive → semantic → component 세 단계로 파생됩니다(`tokens/primitive.css`, `semantic.css`, `component.css`). -- 시각 회귀 골든이 `tests/visual/__snapshots__/`에 있습니다. 화면을 바꾸면 골든도 의도적으로 갱신해야 합니다. -- 템플릿에는 샘플 기능이 없습니다(참조 기능과 예제 화면은 2026-11-07에 지웠습니다). 기능은 `create:feature`로 만듭니다. 디자인 시스템 갤러리와 화면 상태 갤러리는 Storybook story(`src/presentation/design-system/galleries.stories.tsx`)이고 시각 회귀 골든의 대상입니다. 플랫폼 구성 화면(`/examples/platform`)과 홈은 기본 구성입니다. 그래서 갤러리와 홈, 플랫폼 구성 화면에 넣은 디자인은 파생 서비스에 남습니다. -- 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았습니다. +- 하나의 디자인 시스템으로 세 종류의 서비스를 받친다. 업무용·관리 도구(대시보드, 어드민, 설정), 일반 사용자용 웹 서비스, 소개·랜딩 페이지다. +- 디자인 시스템 위치는 `src/presentation/design-system/`이다. 토큰은 primitive → semantic → component 세 단계로 파생된다(`tokens/primitive.css`, `semantic.css`, `component.css`). +- 시각 회귀 골든이 `tests/visual/__snapshots__/`에 있다. 화면을 바꾸면 골든도 의도적으로 갱신해야 한다. +- 템플릿에는 샘플 기능이 없다(참조 기능과 예제 화면은 2026-11-07에 지웠다). 기능은 `create:feature`로 만든다. 디자인 시스템 갤러리와 화면 상태 갤러리는 Storybook story(`src/presentation/design-system/galleries.stories.tsx`)이고 시각 회귀 골든의 대상이다. 플랫폼 구성 화면(`/examples/platform`)과 홈은 기본 구성이다. 그래서 갤러리와 홈, 플랫폼 구성 화면에 넣은 디자인은 파생 서비스에 남는다. +- 어떤 서비스가 먼저 만들어질지, 서비스별 우선순위는 아직 정하지 않았다. ## Brand Commitments -브랜드는 중립으로 유지합니다. 템플릿에는 브랜드 이름·로고·고유 톤을 넣지 않고, 서비스마다 토큰을 바꿔 브랜드를 입힙니다. 현재 표시 이름 "Frontend Skeleton"은 자리표시자입니다. +브랜드는 중립으로 유지한다. 템플릿에는 브랜드 이름·로고·고유 톤을 넣지 않고, 서비스마다 토큰을 바꿔 브랜드를 입힌다. 현재 표시 이름 "Frontend Skeleton"은 자리표시자다. ## Evidence on Hand -- 실제 고객, 사용 후기, 로고, 지표, 가격 정보는 없습니다. 지어내지 않습니다. -- 예제 문구는 템플릿 기능 설명뿐입니다(`src/presentation/i18n/catalog.ts`). +- 실제 고객, 사용 후기, 로고, 지표, 가격 정보는 없다. 지어내지 않는다. +- 예제 문구는 템플릿 기능 설명뿐이다(`src/presentation/i18n/catalog.ts`). - 현재 화면 기록: `tests/visual/__snapshots__/platform.visual.spec.ts-snapshots/`, Storybook(`src/presentation/design-system/design-system.stories.tsx`). ## Product Principles -1. 디자인 시스템은 최종 사용자를 위한 것이고, 예제 화면은 개발자를 위한 것입니다. 둘을 섞지 않습니다. -2. 브랜드는 토큰으로만 바꿉니다. 컴포넌트에 브랜드 값을 직접 넣지 않습니다. -3. 업무 도구, 일반 서비스, 랜딩을 모두 받쳐야 하므로 밀도와 표현 폭은 토큰과 페이지 템플릿에서 조절합니다. 컴포넌트를 서비스 종류별로 복제하지 않습니다. -4. 접근성과 상태 표현(로딩, 빈 상태, 오류, 권한 없음)은 기능이 아니라 기본값입니다. -5. 한국어가 기본이고 영어를 함께 지원합니다. 두 언어의 문구 길이 차이를 견디는 레이아웃이어야 합니다. +1. 디자인 시스템은 최종 사용자를 위한 것이고, 예제 화면은 개발자를 위한 것이다. 둘을 섞지 않는다. +2. 브랜드는 토큰으로만 바꾼다. 컴포넌트에 브랜드 값을 직접 넣지 않는다. +3. 업무 도구, 일반 서비스, 랜딩을 모두 받쳐야 하므로 밀도와 표현 폭은 토큰과 페이지 템플릿에서 조절한다. 컴포넌트를 서비스 종류별로 복제하지 않는다. +4. 접근성과 상태 표현(로딩, 빈 상태, 오류, 권한 없음)은 기능이 아니라 기본값이다. +5. 한국어가 기본이고 영어를 함께 지원한다. 두 언어의 문구 길이 차이를 견디는 레이아웃이어야 한다. ## Accessibility & Inclusion -WCAG 2.2 AA를 기준으로 합니다. 키보드 탐색, 포커스 이동과 복원, 색에만 의존하지 않는 상태 표현, 라이트·다크 테마 모두에서 대비를 지킵니다. 릴리스 후보 하나로 라우트를 사람이 직접 접근성 검토하는 절차가 따로 있습니다(`docs/accessibility/manual-checklist.md`). +WCAG 2.2 AA를 기준으로 한다. 키보드 탐색, 포커스 이동과 복원, 색에만 의존하지 않는 상태 표현, 라이트·다크 테마 모두에서 대비를 지킨다. 릴리스 후보 하나로 라우트를 사람이 직접 접근성 검토하는 절차가 따로 있다(`docs/accessibility/manual-checklist.md`). diff --git a/README.md b/README.md index fbd8f322..28124130 100644 --- a/README.md +++ b/README.md @@ -1,69 +1,101 @@ # Clean Architecture Frontend Template -A React/Vite reference implementation where architecture boundaries, -integration behavior, release coherence, accessibility, performance, and -operations are executable contracts rather than conventions. +React와 Vite로 만든 프론트엔드 참조 구현(reference implementation)이다. 이 템플릿을 복사한 제품 팀이 도메인 기능을 채워 서비스를 만든다. +아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약(게이트와 테스트)으로 지킨다. -## Start locally +## 프로젝트 구조 -Requirements: the exact Node.js version in `.nvmrc` (currently 24.14.0) and -Corepack. The repository pins pnpm in `package.json`. +최상위 폴더와 파일: -Product source, tests, build/quality scripts, and supported tool configuration -are TypeScript/TSX. `allowJs` is disabled. Node-side `.ts` scripts run directly -on the pinned Node 24 runtime and are checked with NodeNext resolution plus -erasable-syntax enforcement. Project-owned executable source contains no -JavaScript-family files; negative architecture, security, and type-compatibility -fixtures are TypeScript/TSX as well. +| 경로 | 하는 일 | 먼저 읽을 곳 | +| --- | --- | --- | +| `src/` | 앱 코드. 아래 표의 폴더로 나뉜다 | `docs/architecture/layers.md` | +| `tests/` | 테스트. 계층별 폴더(`tests/unit/`, `tests/component/`, `tests/integration/`, `tests/e2e/` 등) | `docs/testing/taxonomy.md` | +| `scripts/` | 빌드·검사·생성 명령의 TypeScript 스크립트. `package.json`의 script가 부른다 | `package.json` | +| `config/` | 게이트 목록(`config/ci/`), 런타임 프로필(`config/runtime/`), recipe 카탈로그(`config/recipes/`), JSON Schema(`config/schemas/`), 보안·성능·규모 기준선, 최상위 항목 등록부(`config/repository-layout.json`) | `docs/operations/ci-quality-gates.md` | +| `recipes/` | 선택 기능(recipe)의 원본 코드. 제품이 앱으로 복사해 쓴다. 기본 빌드에 들어가지 않는다 | `docs/architecture/optional-adapter-recipes.md` | +| `docs/` | 문서. 지도는 `docs/README.md` | `docs/README.md` | +| `artifacts/` | 게이트와 시험의 실행 출력. git은 무시하고 `.gitkeep`만 추적한다 | `docs/operations/ci-quality-gates.md` | +| `public/`, `index.html` | 정적 자원과 앱 진입 HTML | `docs/architecture/static-delivery.md` | +| `.gitea/` | CI workflow(`.gitea/workflows/quality-gates.yml`, 생성 파일) | `docs/operations/ci-quality-gates.md` | +| `.storybook/` | Storybook 설정 | `docs/styling/design-tokens.md` | +| `.dependency-cruiser.json` | import 규칙. `check:architecture`가 읽는다 | `docs/architecture/layers.md` | +| `AGENTS.md` | 규칙의 정본과 지도: 꼭 지킬 것, 맡은 일마다 읽을 playbook, 검증 진입점 | `AGENTS.md` | +| `CLAUDE.md`, `.claude/` | Claude Code용: `CLAUDE.md`는 `AGENTS.md`를 가져오고 Claude Code 전용 줄만 둔다. `.claude/`에 경로별 규칙·스킬·서브에이전트·권한·훅 | `CLAUDE.md` | +| `PRODUCT.md` | 디자인 도구가 읽는 제품 맥락 | `PRODUCT.md` | +| `CHANGELOG.md` | 템플릿 버전 사이의 변경과 복사한 프로젝트가 할 일 | `CHANGELOG.md` | + +`src/` 폴더 (설명은 `docs/architecture/layers.md` 표와 같다. 그 문서가 import 규칙도 모두 적는다): + +- `src/bootstrap` — 조립 루트: 런타임 설정, 구체 adapter 생성, React 마운트 +- `src/apps` — 배포 단위 앱: 각 `app-module.ts`가 앱과 그 context 예산을 선언한다. `template-app.ts`가 이 빌드가 만드는 앱이다 +- `src/contexts` — bounded context: 각 `context-module.ts`가 소속 앱, 라우트 루트, 기능 예산을 선언한다 +- `src/features` — 지울 수 있는 수직 slice(`src/features//{domain,application,contracts,adapters,presentation}`)와 설치된 기능 목록(`src/features/*.ts`) +- `src/presentation` — 범용 UI와 inbound adapter: 라우트, 레이아웃, 디자인 시스템, 페이지, provider +- `src/adapters` — application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등 +- `src/application` — 범용 use case, 포트, 정책, view-model +- `src/contracts` — 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registry +- `src/platform` — 어느 폴더든 쓸 수 있는 제품 중립 기본 요소: 예산, 실행 context, 복원력, telemetry 파이프라인, 오류 envelope, 릴리스 정합성 + +의존은 안쪽으로 향한다. 어느 폴더든 `contracts`와 `platform`은 가져와도 된다: + +```text +presentation -> application -> contracts -> platform +adapters -----^ +bootstrap composes concrete adapters +apps -> contexts -> features (an app deploys contexts; a context owns features) +feature use case -> feature port <- feature-owned capability binding +``` + +- 도메인 코드는 각 기능 안에 있다. 최상위 domain 폴더는 없다. +- 기능은 `src/features/` 아래 수직 slice다. 도메인, application 입력, HTTP 연결, 계약, 라우트 런타임, 화면을 그 기능이 소유한다. 중앙 목록은 고른 기능의 기여를 모으기만 한다. +- 템플릿은 기능을 하나도 싣지 않는다(참조 샘플과 예제 화면은 2026-11-07에 지웠다). `corepack pnpm create:feature `가 기능을 만든다. 기능이 없어도 범용 스타터 라우트는 타입 검사·테스트·빌드를 통과한다. +- 불변식: 규칙은 `.dependency-cruiser.json`이 정하고 `check:architecture`가 모든 import를 풀어 검사한다. 해석되지 않은 import, 파싱 실패, 금지된 계층 간선, 순환 의존은 모두 실패로 닫힌다(fail-closed). + +플랫폼 계층의 역할과 경계는 `docs/architecture/frontend-application-foundation.md`, `docs/architecture/overview.md`, `docs/architecture/starter-experience.md`에 있다. + +## 시작하기 + +전제: `.nvmrc`에 적힌 Node.js 버전과 Corepack. pnpm 버전은 `package.json`이 고정한다. ```bash corepack pnpm install --frozen-lockfile corepack pnpm dev ``` -## Runtime configuration +- 성공하면 터미널에 Vite가 알려 준 로컬 주소에서 헤더와 사이드바가 있는 앱 셸이 뜬다. +- 내리려면 그 터미널에서 Ctrl+C를 누른다. -Runtime-public settings are validated against one schema before the product -tree mounts (`runtimeConfigV2ArtifactSchema` in -`src/contracts/release-artifacts.ts`). Client secrets are forbidden. +앱 코드, 테스트, 빌드·품질 스크립트, 도구 설정은 모두 TypeScript/TSX다. `allowJs`는 꺼져 있다. Node 쪽 `.ts` 스크립트는 고정한 Node 런타임에서 바로 돈다. NodeNext 해석과 지울 수 있는 문법(erasable syntax)만 쓰는지로 검사한다. 아키텍처·보안·타입 호환의 음성 fixture도 TypeScript/TSX다. -The source of truth is `config/runtime/.json`, one file per -environment: `local`, `development`, `staging`, `production`. `corepack pnpm -build` writes `dist/config.json` from the selected profile -(`scripts/generate-runtime-config.ts`). `public/config.json` is only the local -profile for `corepack pnpm dev`; the build replaces it, so settings put there -never reach a deployment. Keep it equal to `config/runtime/local.json` plus -`BUILD_ID: local-build` and `RELEASE_ID: local-release`; -`tests/unit/deployment-admission.test.ts` fails when the two differ. +## 런타임 설정과 배포 변수 -Build and deploy variables, lowest precedence first: +런타임에 공개되는 설정은 제품 트리를 마운트하기 전에 스키마 하나로 검증한다(`src/contracts/release-artifacts.ts`의 `runtimeConfigV2ArtifactSchema`). 클라이언트 비밀값은 금지다. -| Variable | Sets | Default | +정본은 환경마다 하나인 `config/runtime/.json`이다: `local`, `development`, `staging`, `production`. + +- `corepack pnpm build`는 고른 프로필로 `dist/config.json`을 쓴다(`scripts/generate-runtime-config.ts`). +- `public/config.json`은 `corepack pnpm dev`용 로컬 프로필일 뿐이다. 빌드가 덮어쓰므로 거기 넣은 설정은 배포에 닿지 않는다. +- `public/config.json`은 `config/runtime/local.json`에 `BUILD_ID: local-build`, `RELEASE_ID: local-release`를 더한 것과 같아야 한다. 다르면 `tests/unit/deployment-admission.test.ts`가 실패한다. + +빌드·배포 변수 (위가 우선순위가 가장 낮다): + +| 변수 | 정하는 것 | 기본값 | | --- | --- | --- | -| `APP_PROFILE` | which `config/runtime/.json` is used | `local`; an empty value fails the build | -| `RUNTIME_API_BASE_URL` | `API_BASE_URL`, overriding the profile; the CI workflow cannot pass it (see below) | the profile value | -| `RUNTIME_TELEMETRY_ENDPOINT` | `TELEMETRY_ENDPOINT`, overriding the profile; the CI workflow cannot pass it (see below) | the profile value | -| `VITE_BUILD_ID` | `BUILD_ID` in the runtime config and the release manifest | `local-build` for `local` and `development`; a `staging` or `production` build fails without it | -| `RELEASE_ID` | `RELEASE_ID` in the runtime config and the release manifest | `local-release` | -| `RELEASE_TARGET` | the environment FE-GATE-027 admits the build to; must equal `APP_PROFILE` | none; admission refuses without it | +| `APP_PROFILE` | 어느 `config/runtime/.json`을 쓰나 | `local`. 빈 값이면 빌드가 실패한다 | +| `RUNTIME_API_BASE_URL` | 프로필을 덮어쓰는 `API_BASE_URL`. CI workflow는 넘길 수 없다(아래) | 프로필 값 | +| `RUNTIME_TELEMETRY_ENDPOINT` | 프로필을 덮어쓰는 `TELEMETRY_ENDPOINT`. CI workflow는 넘길 수 없다(아래) | 프로필 값 | +| `VITE_BUILD_ID` | 런타임 설정과 릴리스 manifest의 `BUILD_ID` | `local`·`development`는 `local-build`. `staging`·`production` 빌드는 없으면 실패한다 | +| `RELEASE_ID` | 런타임 설정과 릴리스 manifest의 `RELEASE_ID` | `local-release` | +| `RELEASE_TARGET` | FE-GATE-027이 빌드를 받아들일 환경. `APP_PROFILE`과 같아야 한다 | 없음. 없으면 승인(admission)이 거절한다 | -`verify:documentation` fails if this table stops naming a variable the build or -admission reads (`scripts/verify-documentation-readiness.ts`). +빌드나 승인이 읽는 변수를 이 표가 빠뜨리면 `verify:documentation`이 실패한다(`scripts/verify-documentation-readiness.ts`). -Only the two `RUNTIME_*` values can differ from the reviewed profile. Anything -else changes by editing the profile file. Staging and production reject demo -auth, non-HTTPS endpoints and the names reserved for examples and tests -(`example.com`, `example.net`, `example.org` and their subdomains, `.example`, -`.invalid`, `.test`). The shipped `staging` and `production` profiles use -`*.example.com`, so admission refuses them until a project sets its own -endpoints. +- 검토한 프로필과 달라질 수 있는 값은 두 `RUNTIME_*`뿐이다. 나머지는 프로필 파일을 고쳐서 바꾼다. +- staging과 production은 demo 인증, HTTPS가 아닌 endpoint, 예시·시험용으로 예약된 이름(`example.com`, `example.net`, `example.org`와 그 하위 도메인, `.example`, `.invalid`, `.test`)을 거절한다. 템플릿의 `staging`·`production` 프로필은 `*.example.com`을 쓰므로 프로젝트가 자기 endpoint를 넣기 전까지 승인이 거절한다. +- CI에서 endpoint를 정하는 길은 `config/runtime/.json`에 커밋하는 것뿐이다. CI 계약은 build job에 `APP_PROFILE`과 `RELEASE_TARGET`만 넘긴다(`scripts/contracts/ci-gates.ts`). 그래서 `RUNTIME_*` repository 변수는 빌드에 닿지 않는다. -In CI the only way to set the endpoints is to commit them to -`config/runtime/.json`. The CI contract binds just `APP_PROFILE` and -`RELEASE_TARGET` to the build job (`scripts/contracts/ci-gates.ts`), so a -`RUNTIME_*` repository variable never reaches the build. - -A local production build and its admission check: +로컬 production 빌드와 그 승인 검사: ```bash APP_PROFILE=production \ @@ -74,321 +106,159 @@ corepack pnpm build APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission ``` -With `CI=true` the gate runner (`corepack pnpm ci:gate`) also requires -`VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH` and `CI_RUNNER_IMAGE` before it runs a -gate (`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). The CI variable -list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md). +`CI=true`이면 게이트 실행기(`corepack pnpm ci:gate`)가 게이트를 돌리기 전에 `VITE_COMMIT_SHA`, `SOURCE_DATE_EPOCH`, `CI_RUNNER_IMAGE`도 요구한다(`scripts/lib/build-environment.ts`, `scripts/run-ci-gate.ts`). CI 변수 목록은 [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md)에 있다. -## Included starter experience +## 기능 켜고 끄기 -The default build mounts a domain-neutral application shell with a header, -responsive sidebar, route focus management, session integration status, a -persistent `system` / `light` / `dark` theme selector, and a language selector. +- **제품 기능**은 `corepack pnpm create:feature `로 만들고 지운다. 절차는 [`docs/manual/`](docs/manual/README.md)에 있다. 기능 폴더만 지우면 테스트·정책 항목·CI 스크립트가 남아 게이트가 실패한다. 지우는 법은 아래 「새 서비스로 시작하기」에 있다. +- **선택 capability**(recipe)는 기본 빌드에 없다. 프로젝트가 `config/recipes/frontend-capability-recipes.json`의 recipe 하나를 복사하고 좁혀서 넣는다. 원칙과 절차는 [`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)에 있다. +- **인증**: `AUTH_MODE=demo`는 자격 증명이 없고 local·development에서만 받는다. 배포는 `AUTH_MODE=external`을 쓰고 [`docs/architecture/starter-experience.md`](docs/architecture/starter-experience.md)가 설명하는 불투명 인증 owner를 준다. 클라이언트 라우트 정책은 사용자 경험일 뿐이다. 권한의 정본은 서버다. -The route list is `ROUTE_REGISTRY` (`src/features/installed-feature-contracts.ts`): -the platform routes of `src/contracts/routes.ts` plus the routes of every -installed feature. The template installs none: `corepack pnpm create:feature` -adds one (`docs/manual/`). The platform overview page (`/examples/platform`) shows the composed list at runtime, so -this README keeps no copy of it and adding a feature does not edit it. +### 기본 화면 -`AUTH_MODE=demo` is credential-free and accepted only in local/development -environments. Deployments use `AUTH_MODE=external` and provide the opaque auth -owner described in -[`docs/architecture/starter-experience.md`](docs/architecture/starter-experience.md). -The client route policy is user experience only; server authorization remains -authoritative. +기본 빌드는 도메인 중립 앱 셸을 마운트한다. 헤더, 반응형 사이드바, 라우트 포커스 관리, 세션 연동 상태, 저장되는 `system` / `light` / `dark` 테마 선택, 언어 선택이 있다. -## Support scope +라우트 목록은 `ROUTE_REGISTRY`(`src/features/installed-feature-contracts.ts`)다. `src/contracts/routes.ts`의 플랫폼 라우트와 설치된 모든 기능의 라우트를 합친다. 템플릿은 기능을 설치하지 않는다. 플랫폼 개요 화면(`/examples/platform`)이 런타임에 합친 목록을 보여 준다. 그래서 이 README는 목록 사본을 두지 않고, 기능을 더해도 고치지 않는다. -Four tiers. The status words on the right are the ones the catalogs and -design documents use; the next table maps them. +### 지원 범위 -| Tier | What it covers | Status words | +네 단계다. 오른쪽 상태 값은 카탈로그와 설계 문서가 쓰는 말이다. 뜻은 다음 표에 있다. + +| 단계 | 무엇이 들어가나 | 상태 값 | | --- | --- | --- | -| Default | In the default build and covered by the merge gates: the application shell and example routes, the REST HTTP executor, TanStack Query server state, Local/Session Storage registries, cross-tab invalidation, runtime config profiles and the release manifest check, `AUTH_MODE=external` (`demo` only in local/development), the typed message catalog, and `create:feature`, which writes a feature that passes the merge gates. `dist/` is served by a static host ([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` | -| Optional (recipe) | Not installed. A project copies one of the recipes in `config/recipes/frontend-capability-recipes.json` and narrows it ([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa` and `file-transfer` also ship a tested reference runtime that the default build leaves out | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` | -| Experimental | Designed and decided, but the runtime is missing or unfinished; finish it before building on it. GraphQL, gRPC-Web, Connect-Web and Protobuf adapters, Range resumable download, IndexedDB query persistence, the local preview decode-safety probe | `DESIGNED_NOT_IMPLEMENTED` | -| Not supported | Deliberately not selected, or browsers cannot guarantee it: SSR, app-managed background upload and download, directory selection, persistent file handles, product query persistence, exactly-once delivery between tabs | `NOT_SELECTED`, `PLATFORM_LIMITED` | +| 기본 | 기본 빌드에 들어가고 merge 게이트가 덮는다: 앱 셸과 예제 라우트, REST HTTP 실행기, TanStack Query 서버 상태, Local/Session Storage registry, 탭 간 무효화, 런타임 설정 프로필과 릴리스 manifest 검사, `AUTH_MODE=external`(`demo`는 local·development만), 타입이 있는 문구 카탈로그, merge 게이트를 통과하는 기능을 만드는 `create:feature`. `dist/`는 정적 호스트가 서빙한다([`docs/architecture/static-delivery.md`](docs/architecture/static-delivery.md)) | `COMPOSED` | +| 선택(recipe) | 설치되지 않는다. 프로젝트가 `config/recipes/frontend-capability-recipes.json`의 recipe를 복사하고 좁힌다([`docs/architecture/optional-adapter-recipes.md`](docs/architecture/optional-adapter-recipes.md)). `realtime`, `offline-indexeddb`, `service-worker-pwa`, `file-transfer`는 시험한 참조 런타임도 싣지만 기본 빌드는 뺀다 | `RECIPE_AVAILABLE`, `NOT_INSTALLED`, `AVAILABLE_NOT_COMPOSED` | +| 실험 | 설계와 결정은 했지만 런타임이 없거나 덜 됐다. 그 위에 짓기 전에 마저 만든다. GraphQL, gRPC-Web, Connect-Web, Protobuf adapter, Range 이어받기 다운로드, IndexedDB query 영속화, 로컬 미리보기 디코드 안전 탐침 | `DESIGNED_NOT_IMPLEMENTED` | +| 지원 안 함 | 일부러 고르지 않았거나 브라우저가 보장하지 못한다: SSR, 앱이 관리하는 백그라운드 업로드·다운로드, 디렉터리 선택, 영속 파일 핸들, 제품 query 영속화, 탭 사이의 정확히 한 번 전달 | `NOT_SELECTED`, `PLATFORM_LIMITED` | -The rows come from -[`docs/architecture/browser-data-capability-completion-ledger.md`](docs/architecture/browser-data-capability-completion-ledger.md), -[`docs/architecture/client-cache-and-storage.md`](docs/architecture/client-cache-and-storage.md) -and -[`docs/architecture/api-contract-schema-mapper-and-server-state.md`](docs/architecture/api-contract-schema-mapper-and-server-state.md). +행의 출처는 설계서 [`docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md`](docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md), [`docs/design/2026-07-28-client-cache-and-storage-design.md`](docs/design/2026-07-28-client-cache-and-storage-design.md), [`docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md`](docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)다. -| Status word | Where it appears | Meaning | Tier | +| 상태 값 | 나오는 곳 | 뜻 | 단계 | | --- | --- | --- | --- | -| `COMPOSED` | capability ledger, design documents | wired into the default production path | Default | -| `INSTALLED` | a project's own recipe catalog (step 10 of the recipe procedure) | the project added the recipe | Default, for that project | -| `RECIPE_AVAILABLE` | recipe catalog `status` | a recipe exists to copy; nothing is installed | Optional | -| `NOT_INSTALLED` | recipe catalog `defaultStatus`; a declared feature the build or `FEATURE_OVERRIDES` left out | not part of the build | Optional (recipe) or Experimental (feature) | -| `AVAILABLE_NOT_COMPOSED` | capability ledger; recipe `referenceRuntime.status` | code and tests exist; the default build leaves it out | Optional | -| `DESIGNED_NOT_IMPLEMENTED` | capability ledger, design documents | design approved, runtime missing | Experimental | -| `NOT_SELECTED` | capability ledger, design documents | deliberately not chosen | Not supported | -| `PLATFORM_LIMITED` | capability ledger | browsers cannot guarantee it; offered only behind a probe and a fallback, if at all | Not supported as a guarantee | +| `COMPOSED` | capability 원장, 설계 문서 | 기본 production 경로에 조립됐다 | 기본 | +| `INSTALLED` | 프로젝트 자신의 recipe 카탈로그(recipe 절차 10단계) | 프로젝트가 recipe를 더했다 | 그 프로젝트에서 기본 | +| `RECIPE_AVAILABLE` | recipe 카탈로그 `status` | 복사할 recipe가 있다. 설치된 것은 없다 | 선택 | +| `NOT_INSTALLED` | recipe 카탈로그 `defaultStatus`. 빌드나 `FEATURE_OVERRIDES`가 뺀 선언된 기능 | 빌드에 없다 | 선택(recipe) 또는 실험(기능) | +| `AVAILABLE_NOT_COMPOSED` | capability 원장, recipe `referenceRuntime.status` | 코드와 테스트가 있지만 기본 빌드가 뺀다 | 선택 | +| `DESIGNED_NOT_IMPLEMENTED` | capability 원장, 설계 문서 | 설계는 승인됐고 런타임이 없다 | 실험 | +| `NOT_SELECTED` | capability 원장, 설계 문서 | 일부러 고르지 않았다 | 지원 안 함 | +| `PLATFORM_LIMITED` | capability 원장 | 브라우저가 보장하지 못한다. 준다면 탐침과 대체 경로 뒤에서만 준다 | 보장으로는 지원 안 함 | -Gate results (`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`) are -verdicts on evidence, not support tiers. +게이트 결과(`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`)는 증거에 대한 판정이지 지원 단계가 아니다. -Browsers: the build targets Chrome and Edge 111, Firefox 128, and Safari and -iOS 16.4. That is the higher of Vite 8's default JavaScript target -(`baseline-widely-available`; `vite.config.ts` sets no `build.target`) and -the CSS targets of Tailwind CSS 4. There is no browserslist. The end-to-end -suite runs on the desktop Chromium, Firefox and WebKit builds that Playwright -1.62 pins, plus one Chromium phone-size smoke (`playwright.config.ts`). Older -versions inside the target range and real mobile browsers are not tested. +브라우저: 빌드 대상은 Chrome·Edge 111, Firefox 128, Safari·iOS 16.4다. -## Architecture +- Vite 기본 JavaScript 대상(`baseline-widely-available`. `vite.config.ts`는 `build.target`을 정하지 않는다)과 Tailwind CSS의 CSS 대상 중 높은 쪽이다. browserslist는 없다. +- end-to-end 시험은 Playwright가 고정한(`package.json`의 `@playwright/test`) 데스크톱 Chromium·Firefox·WebKit과, Chromium 휴대폰 크기 smoke 하나로 돈다(`playwright.config.ts`). +- 대상 범위 안의 더 오래된 버전과 실제 모바일 브라우저는 시험하지 않는다. -This repository is a **Frontend Application Foundation**: a starter/composition -skeleton plus a reusable capability platform. Platform capabilities stay -horizontal while product business features use vertical slices. +## 문서 지도 -`src/` has nine top-level folders. The descriptions match the table in -`docs/architecture/layers.md`, which also names every import rule: +모든 문서 폴더의 지도는 [`docs/README.md`](docs/README.md)다. 거기에 문서의 수명(살아 있는 문서·결정 기록·기록)과 언어 규칙, 기록 문서의 머리 블록 형식도 있다. -- `src/bootstrap` — the composition root: runtime configuration, concrete adapter construction and the React mount -- `src/apps` — deployable apps: each `app-module.ts` declares an app and its context budget; `template-app.ts` is the app this build produces -- `src/contexts` — bounded contexts: each `context-module.ts` declares its app, route root and feature budget -- `src/features` — removable vertical slices (`src/features//{domain,application,contracts,adapters,presentation}`) and the installed-feature catalogs (`src/features/*.ts`) -- `src/presentation` — generic UI and the inbound adapter: routes, layouts, the design system, pages and providers -- `src/adapters` — reusable capability runtimes that implement application ports: HTTP, auth, storage, query cache, telemetry, workers and more -- `src/application` — generic use cases, ports, policies and view-models -- `src/contracts` — shared vocabulary and registries read by several layers, the workers and the build and release scripts -- `src/platform` — product-neutral primitives any folder may use: budgets, execution context, resilience, the telemetry pipeline, error envelopes and release coherence - -Dependencies point inward. Every folder may also import `contracts` and -`platform`: - -```text -presentation -> application -> contracts -> platform -adapters -----^ -bootstrap composes concrete adapters -apps -> contexts -> features (an app deploys contexts; a context owns features) -feature use case -> feature port <- feature-owned capability binding -``` - -Domain code lives inside each feature; there is no top-level domain folder. - -See -`docs/architecture/frontend-application-foundation.md`, -`docs/architecture/overview.md`, `docs/architecture/layers.md`, and -`docs/architecture/starter-experience.md`. A feature is a vertical slice under -`src/features/`; its domain, application input, HTTP binding, contracts, -route runtime, and presentation own their contributions. The central installed -catalogs only aggregate selected contributions. The template ships no feature -(its reference sample and example screens were deleted on 2026-11-07): -`corepack pnpm create:feature ` writes one, and the generic starter routes -typecheck, test, and build without any. - -### Platform capability review - -The starter shell is implemented, but the repository review also records the -remaining work required before feature teams can use every declared contract -through one end-to-end application path: - -- [platform capability review](docs/architecture/frontend-platform-capability-review.md) -- [ports, adapters, and feature boundaries](docs/architecture/frontend-ports-adapters-and-boundaries.md) -- [REST, GraphQL, Connect/gRPC-Web, Schema, Mapper, and Server State](docs/architecture/api-contract-schema-mapper-and-server-state.md) -- [Protobuf browser transports and REST Gateway](docs/architecture/protobuf-browser-transport-and-rest-gateway.md) -- [backend API and Server State handoff contract](docs/architecture/backend-api-and-server-state-contract.md) -- [TypeScript, state ownership, and data flow](docs/architecture/typescript-state-and-data-flow.md) -- [routing, page templates, and reusable patterns](docs/architecture/routing-pages-and-patterns.md) -- [browser data capability completion ledger](docs/architecture/browser-data-capability-completion-ledger.md) -- [browser file and origin-storage platform](docs/architecture/browser-file-and-origin-storage.md) -- [client cache and storage](docs/architecture/client-cache-and-storage.md) -- [realtime events, Web Push, and bounded polling](docs/architecture/realtime-events-web-push-and-bounded-polling.md) -- [presigned transfer, resumable upload, streaming download, and Image CDN](docs/architecture/presigned-transfer-and-image-cdn.md) -- [server file capability infrastructure](docs/architecture/server-file-capability-infrastructure.md) -- [design-system platform](docs/styling/design-system-platform.md) -- [frontend platform testing strategy](docs/testing/frontend-platform-testing-strategy.md) -- [implementation roadmap](docs/architecture/frontend-platform-implementation-roadmap.md) - -These documents distinguish repository defaults from opt-in adapters and -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. -[`docs/manual/`](docs/manual/README.md) is the step-by-step guide (Korean) for -adding a feature, starting from `corepack pnpm create:feature `. -[`AGENTS.md`](AGENTS.md) is the rule book and map that people and coding agents -start from, and [`docs/work/`](docs/work/README.md) is the work manual: one -playbook per kind of task (Korean). Both are part of the template a copy keeps. - -### 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 -(`tests/unit/deletable-history-documents.test.ts` checks this). - -| Path | Contents | +| 무엇 | 어디 | | --- | --- | -| `docs/superpowers/` | past plans and specs | -| `docs/reviews/` | reviews and the review guide. Keep `docs/reviews/adapters/`: `check:adapter-inventory` (FE-GATE-010) reads its `INVENTORY.md`, whose rows link to the adapter reviews beside it, and `docs/operations/adapter-remediation-ledger.md` cites those reviews | -| `SPEC.md`, `docs/history/` | requirements of the 2026-09-25 review fix round (`SPEC.md`), and the plans and evidence of finished work, that round's task list included | -| `docs/ledger/estimates.jsonl` | the template's own task estimates and measurements; empty it and add your project's lines (`docs/ledger/README.md`) | -| `PRODUCT.md` | product context of the template itself (users, purpose, principles) for design tools; replace it with your product's | +| 규칙과 지도(사람과 코딩 에이전트가 먼저 읽는다) | [`AGENTS.md`](AGENTS.md), `src/` 계층 폴더마다의 `AGENTS.md` | +| 작업 매뉴얼: 새 기능, 리뷰·수정, 조사·설계, 문서, 운영, 일 나누기의 playbook과 기준. 완료 기준은 `docs/work/improve.md` 5절 | [`docs/work/`](docs/work/README.md) | +| 개발 매뉴얼: 새 기능을 더하는 순서와 판단 기준, `create:feature` | [`docs/manual/`](docs/manual/README.md) | +| 비전과 문제 정의(소유자가 채우는 양식), 작업 예측·실측 장부 | [`docs/vision.md`](docs/vision.md), [`docs/problem-statement.md`](docs/problem-statement.md), [`docs/ledger/`](docs/ledger/README.md) | +| 현재 계약: 계층과 import 규칙, 스타터, recipe, 정적 배포, 규모 설계, 짝 백엔드 계약 | [`docs/architecture/`](docs/architecture/), [`docs/contracts/`](docs/contracts/), [`docs/security/`](docs/security/), [`docs/styling/`](docs/styling/), [`docs/accessibility/`](docs/accessibility/), [`docs/testing/`](docs/testing/) | +| 운영과 복구: 게이트, 복구 절차, 성능 증거, 오류 code별 runbook | [`docs/operations/`](docs/operations/), [`docs/runbooks/`](docs/runbooks/) | +| 결정 기록(VD) | [`docs/adr/`](docs/adr/) | +| 설계서(쓴 때의 목표 설계) | [`docs/design/`](docs/design/) | +| 기록: 계획서·증거, 리뷰 | [`docs/history/`](docs/history/), [`docs/reviews/`](docs/reviews/) | +| 버전별 변경 | [`CHANGELOG.md`](CHANGELOG.md) | -A feature is not in this list: deleting its directory alone leaves tests, -policy entries and CI scripts behind that fail the gates. -`corepack pnpm test:sample-removal -- --feature=` removes it from a copy of -the repository and lists everything that has to go with it (the header comment -of `scripts/test-sample-removal.ts`); do the same in your project and run the -gates. A sample your project keeps for a while can be listed in -`scripts/lib/removable-template-features.ts`: the drill then removes it without -`--feature`, and the documentation check accepts its paths once its -`feature-module.ts` is gone. +설계서와 기록은 쓴 때의 글이다. 지금 동작은 각 문서 맨 위 머리 블록의 「현재 정본」을 읽는다. -## Verification +## 검증 -Common local checks: +일상 명령: ```bash corepack pnpm lint corepack pnpm check:types -corepack pnpm check:types:app -corepack pnpm check:types:node -corepack pnpm check:types:test corepack pnpm check:architecture corepack pnpm test:all -corepack pnpm test:contract -corepack pnpm test:e2e -corepack pnpm test:a11y corepack pnpm build -corepack pnpm check:bundle -corepack pnpm test:performance -corepack pnpm verify:compatibility -corepack pnpm verify:release -corepack pnpm check:registries -corepack pnpm drill:runbooks -corepack pnpm check:ci ``` -`drill:runbooks` stops at the first drill that is not `PASS`. Without provider -evidence every drill ends `UNVERIFIED` (exit 3), because a drill never reports -a check it could not run locally as `PASS`; see "Runbook jobs" in -[`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md). +- `check:types`는 앱 코드, Node 스크립트·설정, 테스트를 따로 나눈 TypeScript project로 모두 검사한다(`check:types:app`, `check:types:node`, `check:types:test`). 타입·아키텍처·보안·registry의 잘못된 fixture는 `config/ci/gates.json`에서 "실패해야 통과"하는 음성 게이트로 돈다. 도구 호환 결정은 [VD-01](docs/adr/VD-01-typescript-lint-tooling.md)에 있다. +- `test:all`은 평소 제품 개발 루프이고 호스트 수준의 CI runner 검증은 일부러 뺀다. `corepack pnpm test:system`은 [`docs/testing/taxonomy.md`](docs/testing/taxonomy.md)가 말하는 호환 Linux 검증 호스트에서만 돌린다. +- 브라우저 시험 전에 고정한 Playwright 브라우저 엔진을 설치한다: `corepack pnpm exec playwright install --with-deps chromium firefox webkit`. +- 그 밖의 검사(`test:contract`, `test:e2e`, `test:a11y`, `check:bundle`, `test:performance`, `verify:compatibility`, `verify:release`, `check:registries`, `drill:runbooks`, `check:ci`)는 `package.json`과 [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md)에 있다. `drill:runbooks`는 `PASS`가 아닌 첫 드릴에서 멈춘다. provider 증거가 없으면 모든 드릴이 `UNVERIFIED`(exit 3)로 끝난다. 로컬에서 돌리지 못한 검사를 `PASS`로 적지 않기 때문이다. -`test:all` is the ordinary product-development loop and intentionally excludes -host-level CI-runner assurance. Run `corepack pnpm test:system` only on the -compatible Linux assurance host described in -[`docs/testing/taxonomy.md`](docs/testing/taxonomy.md). +### 게이트와 CI -`check:types`는 source, Node scripts/config와 tests를 분리된 TypeScript -project로 모두 검사한다. type/architecture/security/registry의 invalid -fixture는 `config/ci/gates.json`에서 “실패해야 통과”하는 negative gate로 -실행된다. 도구 호환성 결정은 -[VD-01](docs/architecture/decisions/VD-01-typescript-lint-tooling.md)에 기록돼 -있다. - -Application feature input은 module augmentation으로 닫힌 ID와 정확한 input -shape를 제공하며, 공통 `Result`는 error registry의 -failure kind만 application/presentation 경계를 통과시킨다. Architecture gate는 -TypeScript/TSX의 static, dynamic, type import를 별도 정적 그래프로 분석하고 -runtime/source 영역의 JavaScript 재유입도 거절한다. 해석되지 않은 import, -parse failure, 금지 계층 edge와 순환 의존은 모두 fail-closed이며 전용 -TypeScript/TSX negative fixture로도 검증된다. - -Install the pinned Playwright browser engines before the first cross-browser -run: - -```bash -corepack pnpm exec playwright install --with-deps chromium firefox webkit -``` - -Two gates intentionally need external evidence: - -- `review:a11y-manual` (release gate FE-GATE-028) needs a signed human - keyboard/focus/screen-reader review of every registered route, one record - per route at `docs/accessibility/route-reviews/.md`. The routes are - `ROUTE_REGISTRY`; `verify:documentation` fails, naming the route ID, when a - registered route has no record. The merge gate FE-GATE-009 runs only - `review:a11y-manual -- --format-only`, which checks that every route record - keeps the template's fields, reviewed or still pending. -- `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum - eligible-sample threshold and 28 days of production data exist. - -Live hosting verification (FE-GATE-019, production stage) requires -`HOSTING_BASE_URL` and the promoted release deployed by the workflow's -`deployment` job. That job is an empty slot until the project fills it in -`config/ci/product-gates.json` -([`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md)); -until then the result is `UNVERIFIED`, not `PASS`. A host serving another -release fails, and so does one without HTTP/2 or entry compression. - -## CI and evidence - -The gate registry is `config/ci/gates.json`; the Gitea workflow is -`.gitea/workflows/quality-gates.yml`. It follows: +게이트 목록은 `config/ci/gates.json`이고 Gitea workflow는 `.gitea/workflows/quality-gates.yml`이다. 단계 순서: ```text MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY ``` -`DOCUMENTATION_READY` is independent. No gate is downgraded to a warning. +`DOCUMENTATION_READY`는 따로 선다. 경고로 낮춘 게이트는 없다. -The workflow runs on pull requests, pushes to `main` and `develop`, and `v*` -tags. The Git host of this repository may not have Actions enabled, so a pull -request can show no gate status at all; no status is not a pass. Until the -host runs the workflow and marks the merge gates as required checks, run the 14 -merge gates locally before merging (FE-GATE-008 and 009 need Playwright -browsers; FE-GATE-012 builds the app first; FE-GATE-013 needs a Linux host where -bubblewrap may create unprivileged user and network namespaces, which Ubuntu -23.10 and later refuse by default — its first step says so, and -`docs/operations/ci-quality-gates.md` lists the fixes). Product checks listed in -`config/ci/product-gates.json` (`PRODUCT-GATE-NNN`) run in the workflow's own -`product_merge_gate` job, which the release stage waits for: +workflow는 pull request, `main`·`develop` push, `v*` 태그에서 돈다. 이 repo의 Git 호스트는 Actions가 꺼져 있을 수 있다. 그러면 pull request에 게이트 상태가 아예 안 보인다. 상태가 없는 것은 통과가 아니다. 호스트가 workflow를 돌리고 merge 게이트를 필수 검사로 지정하기 전까지는 병합 전에 merge 단계 게이트를 로컬에서 모두 돌린다: ```bash -for gate in 001 002 003 004 005 006 007 008 009 010 011 012 013 020; do - corepack pnpm ci:gate -- "FE-GATE-$gate" || break +for gate in $(node -p 'require("./config/ci/gates.json").stages.find((s) => s.id === "merge").gateIds.join(" ")'); do + corepack pnpm ci:gate -- "$gate" || break done ``` -To run them as the workflow does, give the workflow's environment first. -`CI=true` makes the runner and the release build require the CI build -identity; builds a test makes of a copy (fixture builds, the visual goldens' -build, the dev servers of the browser tests) run as local builds whatever this -says (`localBuildEnvironment` in `scripts/lib/build-environment.ts`). Run it in -a clean clone: `ci:gate` stops a gate at its first failing command. +- FE-GATE-008과 FE-GATE-009는 Playwright 브라우저가 필요하다. FE-GATE-012는 먼저 앱을 빌드한다. +- FE-GATE-013은 bubblewrap이 비특권 user·network namespace를 만들 수 있는 Linux 호스트가 필요하다. Ubuntu 23.10 이후는 기본으로 거절한다. 첫 단계가 그렇게 알려 주고, 고치는 법은 `docs/operations/ci-quality-gates.md`에 있다. +- `config/ci/product-gates.json`에 적은 제품 검사(`PRODUCT-GATE-NNN`)는 workflow의 `product_merge_gate` job에서 돌고, release 단계가 그 job을 기다린다. + +workflow처럼 돌리려면 workflow의 환경을 먼저 준다. `CI=true`이면 실행기와 release 빌드가 CI 빌드 식별값을 요구한다. 테스트가 사본으로 만드는 빌드(fixture 빌드, 시각 골든 빌드, 브라우저 시험의 dev 서버)는 이 값과 상관없이 로컬 빌드로 돈다(`scripts/lib/build-environment.ts`의 `localBuildEnvironment`). 깨끗한 clone에서 돌린다. `ci:gate`는 게이트의 첫 실패 명령에서 멈춘다. ```bash export CI=true VITE_COMMIT_SHA="$(git rev-parse HEAD)" VITE_BUILD_ID=local-ci-1 \ RELEASE_ID=local-ci-1 CI_RUNNER_IMAGE="local/runner@sha256:$(printf 'a%.0s' $(seq 64))" ``` -Machine-readable evidence is written below `artifacts/`; generated evidence is -ignored by Git while `.gitkeep` files preserve the taxonomy. -Run the gates one at a time in a checkout: they and the evidence checks read -the fixed `dist/` and `artifacts/` paths. Two Playwright runs can share a -checkout when each has its own `TEST_RUN_ID`; its build, results and report go -below `.tmp/runs//`. The test servers always pick a free port. The -variables are listed in `docs/testing/frontend-platform-testing-strategy.md` -(13.6). +- 기계가 읽는 증거는 `artifacts/` 아래에 쓴다. 생성된 증거는 git이 무시하고, `.gitkeep` 파일이 폴더 구조를 지킨다. +- 한 checkout에서는 게이트를 하나씩 돌린다. 게이트와 증거 검사가 고정된 `dist/`·`artifacts/` 경로를 읽는다. Playwright 실행 둘은 각자 `TEST_RUN_ID`를 주면 한 checkout을 같이 쓸 수 있다. 그 빌드·결과·보고서는 `.tmp/runs//` 아래로 간다. 시험 서버는 늘 빈 포트를 고른다. 변수 목록은 설계서 `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 13.6절에 있다. -Operational details are in `docs/operations/`, with incident procedures in -`docs/runbooks/`. +외부 증거가 필요한 게이트: -## Updating a copied project +- `review:a11y-manual`(release 게이트 FE-GATE-028)은 등록된 모든 라우트에 대해 사람이 서명한 키보드·포커스·스크린 리더 검토가 필요하다. 라우트마다 기록 하나를 `docs/accessibility/route-reviews/.md`에 둔다. 라우트는 `ROUTE_REGISTRY`다. 등록된 라우트에 기록이 없으면 `verify:documentation`이 라우트 ID를 적고 실패한다. merge 게이트 FE-GATE-009는 `review:a11y-manual -- --format-only`만 돌린다. 모든 라우트 기록이 템플릿의 칸을 지키는지(검토했든 아직이든) 본다. +- `collect:web-vitals-evidence`는 검토한 최소 표본 기준과 28일치 production 데이터가 있기 전까지 `FAIL_UNVERIFIED`다. +- 운영 호스팅 확인(FE-GATE-019, production 단계)은 `HOSTING_BASE_URL`과 workflow의 `deployment` job이 배포한 승격 릴리스가 필요하다. 그 job은 프로젝트가 `config/ci/product-gates.json`에서 채우기 전까지 빈 자리다([`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-gates.md)). 그때까지 결과는 `PASS`가 아니라 `UNVERIFIED`다. 다른 릴리스를 서빙하는 호스트, HTTP/2나 진입 압축이 없는 호스트는 실패한다. -Template versions are Git tags `vX.Y.Z`. [`CHANGELOG.md`](CHANGELOG.md) lists -the changes between tags, marks security fixes **[보안]** and contract changes -**[계약]** (backend, deployment, CI or feature code must change too), and names -the affected paths. Its unreleased section summarizes one sync range (the -section head names the base commit and the branch); take that range as a whole -and do its "먼저 할 일" (BREAKING) steps in order before running the gates. +운영 세부는 `docs/operations/`, 장애 절차는 `docs/runbooks/`에 있다. -Record where you started. Right after copying, commit a one-line -`.template-origin` file at the root of your project with the template tag (or -commit) you copied and the date, for example `v0.2.0 2026-09-26`. +## 새 서비스로 시작하기 -Take a template fix with Git. `cherry-pick` works even when your repository -does not share the template's history, because it merges against the picked -commit's parent: +1. 복사한 바로 뒤에 프로젝트 루트에 한 줄짜리 `.template-origin` 파일을 커밋한다. 복사한 템플릿 태그(또는 커밋)와 날짜를 적는다. 예: `v0.2.0 2026-09-26`. +2. `package.json`의 `name`과 `PRODUCT.md`를 제품 것으로 바꾸고, `docs/vision.md`·`docs/problem-statement.md`를 채운다. `AGENTS.md`·`CLAUDE.md`·`.claude/`·`docs/work/`는 템플릿 계약이라 그대로 받는다. 자기 환경에 맞출 곳은 `docs/work/operate.md` 4.1절과 `docs/work/delegate.md` 4.3절이다. +3. 첫 기능은 `corepack pnpm create:feature `로 만든다([`docs/manual/`](docs/manual/README.md)). +4. 아래 표의 파일을 지웠으면 merge 게이트를 돌린다(「검증」 절). + +### 복사한 뒤 지워도 되는 것 + +템플릿을 만든 과정의 기록이다. 빌드와 게이트는 아래에 적은 파일 하나 말고는 이것들을 읽지 않는다(`tests/unit/deletable-history-documents.test.ts`가 확인한다). + +| 경로 | 내용 | +| --- | --- | +| `docs/history/` | 끝난 작업의 계획서와 증거. 2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록도 여기 있다 | +| `docs/reviews/` | 리뷰와 리뷰 가이드 포인터. `docs/reviews/adapters/`는 남긴다: `check:adapter-inventory`(FE-GATE-010)가 그 안의 `INVENTORY.md`를 읽고, 그 행이 옆의 adapter 리뷰로 링크하며, `docs/operations/adapter-remediation-ledger.md`가 그 리뷰를 인용한다 | +| `docs/ledger/estimates.jsonl` | 템플릿 자신의 작업 예측·실측. 줄을 비우고 자기 프로젝트 줄을 쌓는다(`docs/ledger/README.md`) | +| `PRODUCT.md` | 디자인 도구가 읽는 템플릿 자체의 제품 맥락(사용자, 목적, 원칙). 제품 것으로 바꾼다 | + +기능은 이 목록에 없다. 기능 폴더만 지우면 테스트, 정책 항목, CI 스크립트가 남아 게이트가 실패한다. + +- `corepack pnpm test:sample-removal -- --feature=`가 repo 사본에서 그 기능을 지우고, 같이 지워야 하는 것을 모두 적는다(`scripts/test-sample-removal.ts` 머리 주석). 프로젝트에서 같은 것을 지우고 게이트를 돌린다. +- 프로젝트가 한동안 두는 샘플은 `scripts/lib/removable-template-features.ts`에 적을 수 있다. 그러면 드릴이 `--feature` 없이 지우고, 문서 검사는 그 기능의 `feature-module.ts`가 없어진 뒤 그 경로를 받아들인다. + +### 원본 업데이트 반영 + +템플릿 버전은 Git 태그 `vX.Y.Z`다. [`CHANGELOG.md`](CHANGELOG.md)가 태그 사이의 변경을 적는다. + +- 보안 수정은 **[보안]**, 계약 변경(백엔드·배포·CI·기능 코드도 바꿔야 함)은 **[계약]**으로 표시하고, 영향받는 경로를 적는다. +- 미출시 절은 동기화 범위 하나를 요약한다(절 머리에 기준 커밋과 브랜치가 있다). 그 범위를 통째로 받고, 게이트를 돌리기 전에 그 절의 "먼저 할 일"(BREAKING) 단계를 순서대로 한다. + +템플릿 수정 하나는 Git으로 받는다. `cherry-pick`은 고른 커밋의 부모와 병합하므로 템플릿과 이력을 공유하지 않는 repo에서도 된다: ```bash git remote add template