FE-GATE-008의 Firefox 시험이 가끔 첫 화면 5초 대기에서 실패한다
(old-tab-chunk-recovery.spec.ts, preload-use.spec.ts,
platform-overview.spec.ts). runner run 127과 desktop merge 검증에서
실패했고, 다시 돌리면 통과해 묻혔다.
Playwright는 Firefox 프로필을 os.tmpdir()에 만든다. desktop과 CI job
모두 /tmp가 같은 SATA SSD 위에 있다. Firefox는 시험 context의
localStorage·IndexedDB를 그 프로필(디스크)에 둔다. 그래서 디스크가
붐비면 context마다 첫 localStorage 접근이 디스크 일을 기다린다.
Chromium·WebKit은 시험 context 저장소를 메모리에 둔다. 앱은 첫 렌더
전에 색 구성 설정을 localStorage에서 읽어, 그 대기가 첫 화면 대기에
들어간다. desktop e2e 전체 8회(2026-11-13)에서 Firefox 앱 부팅 463회
중 19회가 0.7~3.8초 멈췄고, Chromium·WebKit은 16 ms를 넘지 않았다.
tests/support/browser/browser-test.ts가 Firefox worker의 프로필을 RAM
파일시스템에 둔다. os.tmpdir()가 이미 tmpfs면 그대로 쓴다. 아니면
/dev/shm에 worker 수 x 64 MB 자리가 있을 때 그 안에 폴더를 만든다.
Playwright의 browser fixture가 launch하는 동안만 TMPDIR를 그 폴더로
돌리고 바로 되돌린다. 그래서 fixture build 같은 다른 임시 파일은
디스크에 그대로 남는다. 프로필이 그 폴더에 생기지 않으면 시험을
실패시킨다. 자리가 없으면 이유를 한 줄 알리고 디스크에 둔다. strict
fixture와 strict를 쓰지 않는 spec 둘(preload-use, chunk-load-error)이
이 test를 바탕으로 쓴다. docs/work/reference/testing.md 5절 표에 원인을
적었다.
버린 대안:
- worker마다 localStorage를 미리 한 번 건드리는 예열: 브라우저 프로세스당
한 번 드는 준비 비용으로 봤다. 예열 뒤에도 19/463이 멈췄다. 예열
context를 바로 닫는 판은 21/464로 더 나빴다.
- toolkit.storage.synchronous=0(SQLite fsync 끔): 15/224로 그대로였다.
- 첫 화면 대기 timeout 늘리기, worker 줄이기: 원인을 덮는다.
- 시험 실행 전체에 TMPDIR 걸기: fixture build까지 RAM에 들어간다.
위험·한계:
- CI job 컨테이너는 /dev/shm이 64 MB다(2026-11-13 runner 확인). /tmp는
같은 SSD 위에 있다. 그래서 CI에서는 프로필이 디스크에 남고 로그에
이유가 한 줄 찍힌다. CI까지 고치려면 runner가 job 컨테이너에 RAM
자리를 줘야 한다(--shm-size 또는 --tmpfs /tmp). runner 설정이라 이
커밋에 넣지 않았다.
- 64 MB/worker는 Firefox worker 6개 프로필 합이 가장 컸을 때 211 MB(1개
35 MB)인 것을 보고 잡은 여유다.
- Playwright의 두 동작에 기댄다. fixture 의존성을 적힌 순서로 준비하는
것과, launch할 때 os.tmpdir()를 읽는 것이다. 어느 쪽이 바뀌어도
폴더가 비므로 시험이 실패해 알린다.
검증(desktop):
- 재현: Firefox 6개를 동시에 띄우고 context 8개씩 localStorage 첫 접근을
쟀다. 프로필 /tmp에서 최대 8,157 ms(384회), /dev/shm에서 최대 17 ms
(384회).
- 수정본 e2e 전체 10회: 매번 189 passed. Firefox 부팅 576회 중 0.5초를
넘는 멈춤 0회(최대 36 ms), 부하 15.9~31.2. 프로필은 매번 /dev/shm에
5~6개, 디스크 0개, 끝난 뒤 남은 폴더 0개.
- 변이: launch 전에 TMPDIR를 돌리지 않게 하면 theme.spec.ts(firefox)가
2 failed, 안전장치 메시지로 실패한다.
- check:types:test, eslint(바뀐 파일), check:test-evidence:source 통과.
- scripts/verify.sh gate FE-GATE-008(CI=true, main ee95573f 위): rc=0 205초,
e2e 189 passed, browser-capabilities 69, storybook 11, visual 7.
- scripts/verify.sh docs, desktop verify:documentation 통과.
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: 라우트, 레이아웃, 디자인 시스템, 페이지, providersrc/adapters— application 포트를 구현하는 재사용 capability 런타임: HTTP, 인증, 저장소, query cache, telemetry, worker 등src/application— 범용 use case, 포트, 정책, view-modelsrc/contracts— 여러 계층·worker·빌드와 릴리스 스크립트가 같이 읽는 공용 어휘와 registrysrc/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_gatejob에서 돌고, 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의deploymentjob이 배포한 승격 릴리스가 필요하다. 그 job은 프로젝트가config/ci/product-gates.json에서 채우기 전까지 빈 자리다(docs/operations/ci-quality-gates.md). 그때까지 결과는PASS가 아니라UNVERIFIED다. 다른 릴리스를 서빙하는 호스트, HTTP/2나 진입 압축이 없는 호스트는 실패한다.
운영 세부는 docs/operations/, 장애 절차는 docs/runbooks/에 있다.
새 서비스로 시작하기
- 복사한 바로 뒤에 프로젝트 루트에 한 줄짜리
.template-origin파일을 커밋한다. 복사한 템플릿 태그(또는 커밋)와 날짜를 적는다. 예:v0.2.0 2026-09-26. package.json의name과PRODUCT.md를 제품 것으로 바꾸고,docs/vision.md·docs/problem-statement.md를 채운다.AGENTS.md·CLAUDE.md·.claude/·docs/work/는 템플릿 계약이라 그대로 받는다. 자기 환경에 맞출 곳은docs/work/operate.md4.1절과docs/work/delegate.md4.3절이다.- 첫 기능은
corepack pnpm create:feature <id>로 만든다(docs/manual/). - 아래 표의 파일을 지웠으면 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의 미출시 절에 적는다.