Files
clean-architecture-frontend…/README.md
T
DongHyeonka e9e98b8aa7 Merge branch 'main' into claude/fe-b-docs-korean-645f55
정리 3·4단계 PR #14와 CI 재편 PR #16(main 38c0dc7d)을 받는다. 충돌은 아홉
파일이다. 이 브랜치가 한국어로 다시 쓴 문서에 두 PR이 영어 판에서 바꾼
것을 한국어로 넣었다.
- a11y 기록 경로 `artifacts/tests/a11y-manual/` → `docs/accessibility/route-reviews/`:
  README, docs/README.md, manual-checklist, starter-experience,
  ci-quality-gates. 문서 검사의 `NOT_DOCUMENT`도 새 경로로 바꿨다(정해진 영어
  키 형식의 게이트 입력이라 문서로 보지 않는다)
- ci-quality-gates.md: merge 단계 job 셋, 지운 CI 계약 기준선, main 단계
  FE-GATE-029의 `check:ci:gating`
- adapter 재검토 원장: 합친 음성 fixture script
- README 프로젝트 구조: `schemas/`는 `config/schemas/`로, `artifacts/`는
  `.gitkeep`만 추적, 최상위 항목 등록부 `config/repository-layout.json`
- verify-documentation-readiness.ts: #14의 배치 규칙 검사(R6·R7)와 이 브랜치의
  문서 체계 검사를 둘 다 둔다. R7의 「현재 문서」는 #14의 폴더 목록(옛
  `docs/superpowers/` 포함) 대신 문서 검사의 `checkedForDrift`로 고른다
- deletable-history-documents 시험: #14의 등록부 기반 경로와 이 브랜치의
  검사기 예외를 같이 둔다
- CHANGELOG: 범위 문장과 표 행을 둘 다 둔다
- 루트 등록부에서 SPEC.md 항목을 뺀다(그 항목이 「문서 체계 작업이 이력 폴더로
  옮기고 이 항목을 뺀다」고 적었다)
- #14가 옛 `docs/testing/frontend-platform-testing-strategy.md`를 고친 것이
  이름 바뀜을 따라 기록(docs/design/…)에 들어와서, 기록은 옮길 때의 글로 되돌렸다
2026-11-12 04:53:06 +09:00

288 lines
28 KiB
Markdown

# 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/<id>/{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/<id>` 아래 수직 slice다. 도메인, application 입력, HTTP 연결, 계약, 라우트 런타임, 화면을 그 기능이 소유한다. 중앙 목록은 고른 기능의 기여를 모으기만 한다.
- 템플릿은 기능을 하나도 싣지 않는다(참조 샘플과 예제 화면은 2026-11-07에 지웠다). `corepack pnpm create:feature <id>`가 기능을 만든다. 기능이 없어도 범용 스타터 라우트는 타입 검사·테스트·빌드를 통과한다.
- 불변식: 규칙은 `.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/<profile>.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/<profile>.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/<profile>.json`에 커밋하는 것뿐이다. CI 계약은 build job에 `APP_PROFILE`과 `RELEASE_TARGET`만 넘긴다(`scripts/contracts/ci-gates.ts`). 그래서 `RUNTIME_*` repository 변수는 빌드에 닿지 않는다.
로컬 production 빌드와 그 승인 검사:
```bash
APP_PROFILE=production \
RUNTIME_API_BASE_URL=<your-api-origin>/ \
RUNTIME_TELEMETRY_ENDPOINT=<your-telemetry-endpoint> \
VITE_BUILD_ID=<unique build id> RELEASE_ID=<unique 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 <id>`로 만들고 지운다. 절차는 [`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/<id>/` 아래로 간다. 시험 서버는 늘 빈 포트를 고른다. 변수 목록은 설계서 `docs/design/2026-07-26-frontend-platform-testing-strategy-design.md` 13.6절에 있다.
외부 증거가 필요한 게이트:
- `review:a11y-manual`(release 게이트 FE-GATE-028)은 등록된 모든 라우트에 대해 사람이 서명한 키보드·포커스·스크린 리더 검토가 필요하다. 라우트마다 기록 하나를 `docs/accessibility/route-reviews/<ROUTE_ID>.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 <id>`로 만든다([`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=<id>`가 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 <template repository URL>
git fetch template --tags
git log --oneline <your origin>..template/main # what changed since you copied
git cherry-pick -x <commit> # one fix; -x records its origin
```
미출시 범위는 통째로 받는다. 템플릿과 이력을 공유하는 repo는 그 범위의 브랜치를 병합한다. 공유하지 않는 repo(파일 사본에서 시작함)는 범위 기준점과 3-way 병합한다. 양쪽이 바꾼 파일은 충돌로 남으니 풀고 커밋한다:
```bash
git merge --no-ff template/<range branch> # shared history
git merge-recursive <range base> -- HEAD template/<range branch> # no shared history
```
- 동기화한 기준점은 프로젝트가 적어 두는 곳에 둔다: `.template-origin`, 또는 자기 잠금 파일(tech-log는 `template.lock.json`의 `sourceRevision`). 범위를 다 받으면 그 끝으로 옮긴다.
- 파일이 너무 옮겨졌거나 갈라져서 깨끗하게 고를 수 없으면 diff로 읽고 손으로 적용한다: `git diff <commit>^ <commit> -- <paths from CHANGELOG>`.
- 받은 뒤 「검증」 절의 로컬 merge 게이트를 돌리고, **[계약]** 행이 말하는 백엔드·배포 변경을 하고, 태그까지 따라잡았으면 `.template-origin`을 고친다. 받은 수정은 `git revert`로 되돌린다.
결함: 바꾸지 않은 `.template-origin` 커밋 checkout에서 재현되면 템플릿 결함이다. 그 커밋과 재현 방법을 템플릿 repo에 알린다. 템플릿 관리자가 분류하고 CHANGELOG 항목과 함께 수정을 낸다. 프로젝트의 변경이 있어야 재현되는 문제는 프로젝트의 몫이고, 템플릿 수정을 자기 사본에 적용하는 것도 프로젝트의 일이다.
## 규칙과 기여
- 규칙의 정본은 `AGENTS.md`다. `CLAUDE.md`는 `@AGENTS.md`로 가져오고 Claude Code 전용 줄만 둔다. 리뷰 기준은 `docs/work/reference/review-criteria.md`다.
- 커밋 메시지와 PR 본문은 design-docs 저장소의 `conventions/commit-and-pr.md`를 따른다. 문서 규칙의 정본은 같은 저장소의 `conventions/docs-system.md`이고, 이 repo의 적용은 [`docs/README.md`](docs/README.md)에 있다.
- 코드나 규칙을 바꾸는 변경은 그것을 설명하는 살아 있는 문서를 같은 변경에서 고친다. 공개 계약을 바꾸면 `CHANGELOG.md`의 미출시 절에 적는다.