DongHyeonka 838ed410f7 fix(styles): 스타일이 간격·글자·층·그림자 토큰을 읽고 검사가 날 값을 거절한다
셸·페이지 템플릿·카드 CSS가 간격·글자·반경·층·그림자 토큰을 건너뛰고 날
값을 쓴다(`src/presentation/styles/theme/*.css`에서 규칙에 걸리는 선언
118개). `shell.css`·`pages.css`·`templates.css`는 `var(--space-*)`를 한
번도 쓰지 않았고, z-index 100·30·10, 카드·헤더의 손 그림자, `999px`,
`min-height: 2.75rem`이 토큰과 같은 값을 다시 적었다. 필수 semantic 토큰
가운데 `--layer-navigation`·`--layer-modal`·`--opacity-scrim`·
`--opacity-skeleton`·`--elevation-panel`·`--color-disabled-content`·
`--color-action-pressed`를 읽는 스타일이 없었다. 그래서 파생 서비스가
밀도·층·그림자를 토큰으로 바꿔도 화면이 그대로다. 그리고 component.css의
가림막 토큰 셋이 `REQUIRED_COMPONENT_TOKENS`에 없어 UI-03 밖이었다(04-12).

고른 방법:
- 날 값을 토큰으로 바꾼다. 맞는 단계가 없는 간격은 가까운 `--space-*`로
  반올림했다(0.15~0.35rem → 1, 0.4~0.55 → 2, 0.65~0.85 → 3, 0.9 → 4).
  큰 값 3.5rem·4rem은 `--space-14`·`--space-16`을 더했다. 글자 크기도
  가까운 단계(0.8 → xs, 0.8125~0.9 → sm, 1.05 → md, 1.1 → lg, 1.35 → xl),
  굵기 600·650 → semibold, 700·750·800 → bold, 줄 높이 1.5~1.6 → normal,
  1.65·1.7 → relaxed. 페이지 h1은 semantic `--font-size-heading-1`·
  `--line-height-heading-1`(새 primitive 단계 3xl·4xl·compact)을 읽는다.
- 층: skip link는 `--layer-navigation`, sticky 헤더와 sticky 폼 버튼은
  `--layer-sticky`. 그림자: 카드·패널·갤러리 안내는 `--elevation-panel`,
  헤더는 새 `--elevation-sticky`(`--shadow-sticky`). `.ui-panel`의 Tailwind
  `shadow-sm`도 `--elevation-panel`로 바꿔 카드와 같은 높이가 됐다. dialog는
  `--radius-modal`, 가림막 비율은 `--opacity-scrim`을 읽고
  `--dialog-backdrop-weight`는 지웠다.
- 읽는 곳이 없던 semantic 토큰: skeleton 깜박임이 `--opacity-skeleton`,
  꺼진 입력이 `--color-disabled-content`·`--color-disabled-surface`, 누른
  primary 버튼이 새 component 토큰 `--button-primary-pressed`
  (`--color-action-pressed`)를 읽는다. `--layer-modal`은 native `<dialog>`가
  top layer에 열려 z-index가 닿지 않으므로 이유와 함께
  `SEMANTIC_TOKENS_WITHOUT_TEMPLATE_READER`에 둔다.
- `check:design-system`에 셋을 더한다. UI-06: styles 아래 간격·글자·반경·
  z-index·그림자의 날 값을 줄 번호와 함께 거절한다. UI-03을 필수 semantic
  토큰으로 넓힌다. component.css `@theme`의 토큰이 모두 계약에 있어야 한다.
  계약에 `--button-primary-pressed`, `--dialog-backdrop`,
  `--dialog-backdrop-on-surface`를 더했다.
- 버린 대안: 맞는 단계가 없는 값마다 primitive 단계를 더하기(단계가 두 배로
  늘어 scale이 무의미해진다). `--layer-modal`을 dialog에 z-index로 읽히기
  (top layer에서는 효과가 없는 가짜 읽기다).

위험·한계: 반올림과 패널 그림자 때문에 화면이 조금 바뀐다(간격 최대
0.15rem, 굵기 800 → 750, 패널 그림자 크기). 시각 골든은 이 커밋에서 다시
찍고 차이를 PR 본문에 적는다. 다운스트림이 styles에 날 값을 더해 두었으면
UI-06이 그 줄을 알린다. 너비·높이·위치(top 등)와 opacity는 UI-06 밖이다.

검증: 규칙 단위 시험과 check-design-system 연결 시험, 새 검사기로 고치기
전 CSS를 돌린 결과(RED), 시각 골든은 desktop에서 돌려 PR 본문에 적는다.

Refs: 1112/04-08, 1112/04-12
2026-11-13 23:27:47 +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은 systemd와 bubblewrap이 있는 호스트가 필요해 scripts/run-in-system-container.sh가 띄우는 privileged systemd 컨테이너 안에서 돈다. Docker가 그런 컨테이너를 띄울 수 있어야 한다. 위 반복문에서는 scripts/run-in-system-container.sh corepack pnpm ci:gate -- FE-GATE-013으로 돌린다. 자세한 조건은 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>/ 아래로 간다. 시험 서버는 늘 빈 포트를 고른다. 변수 목록의 정본은 scripts/lib/run-isolation.ts(TEST_RUN_ID_VARIABLE, TEST_PORT_VARIABLES)다.

외부 증거가 필요한 게이트:

  • 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). 범위를 다 받고 아래 게이트가 통과하면 그 끝으로 옮긴다.
  • 충돌을 풀 때 어느 파일이 제품 몫인지는 매뉴얼 03 문서의 C절(조건이 맞을 때만 사람이 고친다)과 D절(고치지 않는다)이 정본이다. D절의 파일은 템플릿 쪽을 받는다.
  • 파일이 너무 옮겨졌거나 갈라져서 깨끗하게 고를 수 없으면 diff로 읽고 손으로 적용한다: git diff <commit>^ <commit> -- <paths from CHANGELOG>.
  • 받은 뒤 「검증」 절의 로컬 merge 게이트를 돌리고, [계약] 행이 말하는 백엔드·배포 변경을 하고, 위 기준점을 받은 범위의 끝으로 옮긴다. 받은 수정은 git revert로 되돌린다.

결함: 바꾸지 않은 .template-origin 커밋 checkout에서 재현되면 템플릿 결함이다. 템플릿이 주는 선택 기능(opt-in recipe·adapter, create:feature가 만든 기능)을 문서대로 켜거나 더한 것만 다르고 재현되는 것도 템플릿 결함이다. 그 커밋, 켠 선택 기능, 재현 방법을 템플릿 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%