DongHyeonka 1b3eee41e3 test(claude): 스킬이 인용하는 절 이름을 문서 제목과 대조한다
문제: 스킬은 정본 문서의 절을 「이름」이나 「N절」로 가리킨다. 문서 검사
(verify:documentation)는 경로만 보므로, 문서를 번역하거나 절을 바꾸면
인용한 절이 사라져도 통과한다. 지금 9곳이 그렇다.
- fe-structure: 「Decision rule」(지금 「판단 규칙」), 「The adapter
  kernel」(지금 「adapter kernel」)
- fe-a11y: 「What the automated run scans」, 「Included primitives」
- fe-design-system: 「Arbitrary-value policy」
- fe-performance: 「Service Worker steps」
- fe-ux: 「routing 6.4절」이 앞 인용(typescript 설계서)의 6.4절로 읽힌다.
  그 설계서에는 6.4절이 없다.
- desktop-gates: 경로 없이 `gates.md`·`operate.md`라고만 쓴다.

고른 방법: scripts/tests/test_claude_setup.py의 SkillTest에 시험을 더한다.
- 모든 repo 스킬에서 읽는 인용 꼴: `경로.md` 「이름」, `경로.md` N절
  (3·4절, 6.1·11절), `경로.md` N절 「이름」, 같은 문서 N절,
  `fe-x` 「이름」(다른 스킬의 절).
- 인용마다 대상 파일에 그 제목이 있는지 본다. 제목은 앞 번호와 끝 괄호를
  뗀 꼴도 받는다. 「이름:」만 있는 소제목 줄도 받는다. 코드 블록 안 제목은
  보지 않는다.
- 파서와 제목 읽기를 따로 고정하는 시험 둘을 함께 둔다.
- 9곳은 지금 제목으로 고치고, 짧게 쓴 경로는 전체 경로로 쓴다.
버린 대안: 문서 검사(scripts/lib/docs-system.ts)에 넣는 방법. 스킬
구성의 다른 규칙이 이미 이 시험 파일에 있고, `scripts/verify.sh hooks`로
노트북에서 바로 돈다.

위험: 「 」 안의 말이 절 이름이 아닌데 경로 바로 뒤에 붙으면 거짓 실패가
난다. 경로 뒤의 —, 괄호, 문장 끝에서 읽기를 멈춰 지금 196개 인용에는 그런
경우가 없다. 「N절」이 다른 문서를 줄여 부르면(「routing 6.4절」) 앞 경로로
읽으니 전체 경로로 쓴다. 이 시험은 게이트가 아니라 hooks 단계에서 돈다.

검증: python3 -m unittest scripts.tests.test_claude_setup.
- 고치기 전: 새 시험이 9곳(과 처음 판에서 거짓 실패 2곳)을 냈다(RED).
- 고친 뒤: 24개 모두 통과했다. 인용 196개를 확인했다.
2026-11-12 10:49:20 +09:00
2026-08-01 19:39:59 +09:00

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은 가져와도 된다:

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이 고정한다.

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 빌드와 그 승인 검사:

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에 있다.

기능 켜고 끄기

  • 제품 기능은 corepack pnpm create:feature <id>로 만들고 지운다. 절차는 docs/manual/에 있다. 기능 폴더만 지우면 테스트·정책 항목·CI 스크립트가 남아 게이트가 실패한다. 지우는 법은 아래 「새 서비스로 시작하기」에 있다.
  • 선택 capability(recipe)는 기본 빌드에 없다. 프로젝트가 config/recipes/frontend-capability-recipes.json의 recipe 하나를 복사하고 좁혀서 넣는다. 원칙과 절차는 docs/architecture/optional-adapter-recipes.md에 있다.
  • 인증: AUTH_MODE=demo는 자격 증명이 없고 local·development에서만 받는다. 배포는 AUTH_MODE=external을 쓰고 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) COMPOSED
선택(recipe) 설치되지 않는다. 프로젝트가 config/recipes/frontend-capability-recipes.json의 recipe를 복사하고 좁힌다(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-28-client-cache-and-storage-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다. 거기에 문서의 수명(살아 있는 문서·결정 기록·기록)과 언어 규칙, 기록 문서의 머리 블록 형식도 있다.

무엇 어디
규칙과 지도(사람과 코딩 에이전트가 먼저 읽는다) AGENTS.md, src/ 계층 폴더마다의 AGENTS.md
작업 매뉴얼: 새 기능, 리뷰·수정, 조사·설계, 문서, 운영, 일 나누기의 playbook과 기준. 완료 기준은 docs/work/improve.md 5절 docs/work/
개발 매뉴얼: 새 기능을 더하는 순서와 판단 기준, create:feature docs/manual/
비전과 문제 정의(소유자가 채우는 양식), 작업 예측·실측 장부 docs/vision.md, docs/problem-statement.md, docs/ledger/
현재 계약: 계층과 import 규칙, 스타터, recipe, 정적 배포, 규모 설계, 짝 백엔드 계약 docs/architecture/, docs/contracts/, docs/security/, docs/styling/, docs/accessibility/, docs/testing/
운영과 복구: 게이트, 복구 절차, 성능 증거, 오류 code별 runbook docs/operations/, docs/runbooks/
결정 기록(VD) docs/adr/
설계서(쓴 때의 목표 설계) docs/design/
기록: 계획서·증거, 리뷰 docs/history/, docs/reviews/
버전별 변경 CHANGELOG.md

설계서와 기록은 쓴 때의 글이다. 지금 동작은 각 문서 맨 위 머리 블록의 「현재 정본」을 읽는다.

검증

일상 명령:

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에 있다.
  • test:all은 평소 제품 개발 루프이고 호스트 수준의 CI runner 검증은 일부러 뺀다. corepack pnpm test:system은 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에 있다. drill:runbooks는 PASS가 아닌 첫 드릴에서 멈춘다. provider 증거가 없으면 모든 드릴이 UNVERIFIED(exit 3)로 끝난다. 로컬에서 돌리지 못한 검사를 PASS로 적지 않기 때문이다.

게이트와 CI

게이트 목록은 config/ci/gates.json이고 Gitea workflow는 .gitea/workflows/quality-gates.yml이다. 단계 순서:

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 단계 게이트를 로컬에서 모두 돌린다:

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는 게이트의 첫 실패 명령에서 멈춘다.

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). 그때까지 결과는 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/).
  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가 태그 사이의 변경을 적는다.

  • 보안 수정은 [보안], 계약 변경(백엔드·배포·CI·기능 코드도 바꿔야 함)은 **[계약]**으로 표시하고, 영향받는 경로를 적는다.
  • 미출시 절은 동기화 범위 하나를 요약한다(절 머리에 기준 커밋과 브랜치가 있다). 그 범위를 통째로 받고, 게이트를 돌리기 전에 그 절의 "먼저 할 일"(BREAKING) 단계를 순서대로 한다.

템플릿 수정 하나는 Git으로 받는다. cherry-pick은 고른 커밋의 부모와 병합하므로 템플릿과 이력을 공유하지 않는 repo에서도 된다:

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 병합한다. 양쪽이 바꾼 파일은 충돌로 남으니 풀고 커밋한다:

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에 있다.
  • 코드나 규칙을 바꾸는 변경은 그것을 설명하는 살아 있는 문서를 같은 변경에서 고친다. 공개 계약을 바꾸면 CHANGELOG.md의 미출시 절에 적는다.
S
Description
No description provided
Readme
20 MiB
Languages
TypeScript 98.2%
Python 1%
CSS 0.5%
Shell 0.3%