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 b74de10f..d9494b2b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ # 변경 이력 이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다. -가져오는 방법은 `README.md`의 "Updating a copied project" 절에 있다. +가져오는 방법은 `README.md`의 「원본 업데이트 반영」 절에 있다. - 버전은 git 태그 `vX.Y.Z`로 식별한다. 태그 사이의 변경을 여기 적는다. - 미출시 절은 한 번의 동기화 단위(기준 커밋 → 브랜치 끝)에서 받는 변경의 순 요약이다. 최종 상태만 적고, 같은 범위 안에서 뒤 커밋이 바꾼 중간 상태는 지운다. 호환을 깨는 변경은 절 첫머리 "먼저 할 일"에 옮기기 전·옮기는 법·옮긴 뒤 확인 순서로 적는다. diff --git a/README.md b/README.md index 4d2d483e..c3594fe5 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/`), 보안·성능·규모 기준선 | `docs/operations/ci-quality-gates.md` | +| `schemas/` | 설정 파일과 산출물의 JSON Schema | `config/` | +| `recipes/` | 선택 기능(recipe)의 원본 코드. 제품이 앱으로 복사해 쓴다. 기본 빌드에 들어가지 않는다 | `docs/architecture/optional-adapter-recipes.md` | +| `docs/` | 문서. 지도는 `docs/README.md` | `docs/README.md` | +| `artifacts/` | 게이트가 쓰는 증거 산출물. git은 무시하고, 수동 접근성 검토 기록(`artifacts/tests/a11y-manual/`)만 추적한다 | `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` | +| `CLAUDE.md` | 이 repo를 리뷰할 때의 기준 | `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,318 +106,156 @@ 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/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) -and -[`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). +행의 출처는 설계서 [`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/design/2026-07-26-frontend-platform-capability-review-design.md) -- [ports, adapters, and feature boundaries](docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md) -- [REST, GraphQL, Connect/gRPC-Web, Schema, Mapper, and Server State](docs/design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md) -- [Protobuf browser transports and REST Gateway](docs/design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md) -- [backend API and Server State handoff contract](docs/architecture/backend-api-and-server-state-contract.md) -- [TypeScript, state ownership, and data flow](docs/design/2026-07-26-typescript-state-and-data-flow-design.md) -- [routing, page templates, and reusable patterns](docs/design/2026-07-26-routing-pages-and-patterns-design.md) -- [browser data capability completion ledger](docs/design/2026-07-30-browser-data-capability-completion-ledger-design.md) -- [browser file and origin-storage platform](docs/design/2026-07-27-browser-file-and-origin-storage-design.md) -- [client cache and storage](docs/design/2026-07-28-client-cache-and-storage-design.md) -- [realtime events, Web Push, and bounded polling](docs/design/2026-07-30-realtime-events-web-push-and-bounded-polling-design.md) -- [presigned transfer, resumable upload, streaming download, and Image CDN](docs/design/2026-07-30-presigned-transfer-and-image-cdn-design.md) -- [server file capability infrastructure](docs/design/2026-07-28-server-file-capability-infrastructure-design.md) -- [design-system platform](docs/design/2026-07-26-design-system-platform-design.md) -- [frontend platform testing strategy](docs/design/2026-07-26-frontend-platform-testing-strategy-design.md) -- [implementation roadmap](docs/design/2026-07-26-frontend-platform-implementation-roadmap-design.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 `. - -### 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 | -| `CLAUDE.md` | review instructions for the template repository itself; replace it with your own | -| `PRODUCT.md` | product context of the template itself (users, purpose, principles) for design tools; replace it with your product's | +| 개발 매뉴얼: 새 기능을 더하는 순서와 판단 기준, `create:feature`, 완료 기준 | [`docs/manual/`](docs/manual/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/adr/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 `artifacts/tests/a11y-manual/.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/design/2026-07-26-frontend-platform-testing-strategy-design.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)은 등록된 모든 라우트에 대해 사람이 서명한 키보드·포커스·스크린 리더 검토가 필요하다. 라우트마다 기록 하나를 `artifacts/tests/a11y-manual/.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`를 제품 것으로 바꾼다. `CLAUDE.md`는 자기 리뷰 기준으로 바꾼다. +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`가 그 리뷰를 인용한다 | +| `CLAUDE.md` | 템플릿 repo 자체의 리뷰 지침. 자기 것으로 바꾼다 | +| `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