# Clean Architecture Frontend Template React와 Vite로 만든 프론트엔드 참조 구현(reference implementation)이다. 이 템플릿을 복사한 제품 팀이 도메인 기능을 채워 서비스를 만든다. 아키텍처 경계, 연동 동작, 릴리스 정합성, 접근성, 성능, 운영을 관례가 아니라 실행되는 계약(게이트와 테스트)으로 지킨다. ## 프로젝트 구조 최상위 폴더와 파일: | 경로 | 하는 일 | 먼저 읽을 곳 | | --- | --- | --- | | `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 ``` - 성공하면 터미널에 Vite가 알려 준 로컬 주소에서 헤더와 사이드바가 있는 앱 셸이 뜬다. - 내리려면 그 터미널에서 Ctrl+C를 누른다. 앱 코드, 테스트, 빌드·품질 스크립트, 도구 설정은 모두 TypeScript/TSX다. `allowJs`는 꺼져 있다. Node 쪽 `.ts` 스크립트는 고정한 Node 런타임에서 바로 돈다. NodeNext 해석과 지울 수 있는 문법(erasable syntax)만 쓰는지로 검사한다. 아키텍처·보안·타입 호환의 음성 fixture도 TypeScript/TSX다. ## 런타임 설정과 배포 변수 런타임에 공개되는 설정은 제품 트리를 마운트하기 전에 스키마 하나로 검증한다(`src/contracts/release-artifacts.ts`의 `runtimeConfigV2ArtifactSchema`). 클라이언트 비밀값은 금지다. 정본은 환경마다 하나인 `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` | 어느 `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`이 실패한다(`scripts/verify-documentation-readiness.ts`). - 검토한 프로필과 달라질 수 있는 값은 두 `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 변수는 빌드에 닿지 않는다. 로컬 production 빌드와 그 승인 검사: ```bash APP_PROFILE=production \ RUNTIME_API_BASE_URL=/ \ RUNTIME_TELEMETRY_ENDPOINT= \ VITE_BUILD_ID= RELEASE_ID= \ corepack pnpm build APP_PROFILE=production RELEASE_TARGET=production corepack pnpm check:release-admission ``` `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)에 있다. ## 기능 켜고 끄기 - **제품 기능**은 `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를 준다. 클라이언트 라우트 정책은 사용자 경험일 뿐이다. 권한의 정본은 서버다. ### 기본 화면 기본 빌드는 도메인 중립 앱 셸을 마운트한다. 헤더, 반응형 사이드바, 라우트 포커스 관리, 세션 연동 상태, 저장되는 `system` / `light` / `dark` 테마 선택, 언어 선택이 있다. 라우트 목록은 `ROUTE_REGISTRY`(`src/features/installed-feature-contracts.ts`)다. `src/contracts/routes.ts`의 플랫폼 라우트와 설치된 모든 기능의 라우트를 합친다. 템플릿은 기능을 설치하지 않는다. 플랫폼 개요 화면(`/examples/platform`)이 런타임에 합친 목록을 보여 준다. 그래서 이 README는 목록 사본을 두지 않고, 기능을 더해도 고치지 않는다. ### 지원 범위 네 단계다. 오른쪽 상태 값은 카탈로그와 설계 문서가 쓰는 말이다. 뜻은 다음 표에 있다. | 단계 | 무엇이 들어가나 | 상태 값 | | --- | --- | --- | | 기본 | 기본 빌드에 들어가고 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` | 행의 출처는 설계서 [`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)다. | 상태 값 | 나오는 곳 | 뜻 | 단계 | | --- | --- | --- | --- | | `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 원장 | 브라우저가 보장하지 못한다. 준다면 탐침과 대체 경로 뒤에서만 준다 | 보장으로는 지원 안 함 | 게이트 결과(`PASS`, `PASS_SCOPED`, `UNVERIFIED`, `FAIL_UNVERIFIED`)는 증거에 대한 판정이지 지원 단계가 아니다. 브라우저: 빌드 대상은 Chrome·Edge 111, Firefox 128, Safari·iOS 16.4다. - 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`). - 대상 범위 안의 더 오래된 버전과 실제 모바일 브라우저는 시험하지 않는다. ## 문서 지도 모든 문서 폴더의 지도는 [`docs/README.md`](docs/README.md)다. 거기에 문서의 수명(살아 있는 문서·결정 기록·기록)과 언어 규칙, 기록 문서의 머리 블록 형식도 있다. | 무엇 | 어디 | | --- | --- | | 규칙과 지도(사람과 코딩 에이전트가 먼저 읽는다) | [`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) | 설계서와 기록은 쓴 때의 글이다. 지금 동작은 각 문서 맨 위 머리 블록의 「현재 정본」을 읽는다. ## 검증 일상 명령: ```bash corepack pnpm lint corepack pnpm check:types corepack pnpm check:architecture corepack pnpm test:all corepack pnpm build ``` - `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`로 적지 않기 때문이다. ### 게이트와 CI 게이트 목록은 `config/ci/gates.json`이고 Gitea workflow는 `.gitea/workflows/quality-gates.yml`이다. 단계 순서: ```text MERGE_READY -> RELEASE_READY -> PROD_PROMOTION_READY -> FIELD_SLO_READY ``` `DOCUMENTATION_READY`는 따로 선다. 경고로 낮춘 게이트는 없다. workflow는 pull request, `main`·`develop` push, `v*` 태그에서 돈다. 이 repo의 Git 호스트는 Actions가 꺼져 있을 수 있다. 그러면 pull request에 게이트 상태가 아예 안 보인다. 상태가 없는 것은 통과가 아니다. 호스트가 workflow를 돌리고 merge 게이트를 필수 검사로 지정하기 전까지는 병합 전에 merge 단계 게이트를 로컬에서 모두 돌린다: ```bash 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 ``` - 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))" ``` - 기계가 읽는 증거는 `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절에 있다. 외부 증거가 필요한 게이트: - `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나 진입 압축이 없는 호스트는 실패한다. 운영 세부는 `docs/operations/`, 장애 절차는 `docs/runbooks/`에 있다. ## 새 서비스로 시작하기 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