문제 예산 204,800 B는 템플릿을 받을 때의 기본값이다. TechLog는 기능을 붙인 뒤 예산을 다시 정하지 않았다(템플릿 문서는 첫 기능을 추가하기 전에 정하라고 한다). 앞 커밋들로 초기 JS를 300,869 B에서 229,224 B로 줄였지만, 템플릿 공통 부분(react-dom·react-router·zod·tanstack·플랫폼 src)만 약 205 KB여서 TechLog 코드를 모두 빼도 204,800 B 안에 들지 않는다. 고른 방법 - 템플릿 규칙(1106/15-01, 결정 D9)을 그대로 쓴다. CI env 측정값에 기능 하나의 상한 1 KiB를 더해 KiB 단위로 올린다. 229,224 + 1,024 = 230,248 B → 225 KiB = 230,400 B. 여유 1,176 B는 기능 하나와 올림 몫이다. - docs/operations/performance-evidence.md에 전후 수치, 뺀 것, 204,800 B로 돌아가지 못한 이유, 다시 볼 조건과 되돌림 규칙을 적는다. feature-shape-ceilings.json의 예산 언급도 맞춘다. 버린 대안 - 남은 TechLog 몫(문구 catalog 약 7.5 KB, 공개 HTTP gateway·mapping 약 6.7 KB, Studio·관리·공개 계약 약 6.6 KB, 모듈 단독 gzip)을 더 빼기. 문구와 계약은 부팅 때 합쳐 검증하는 구조라, 템플릿 15-01(기능 실행부를 라우트 진입 때 적재)을 옮기는 템플릿 동기화 일이다. 공개 gateway는 첫 화면 데이터 요청에 쓰인다. 위험·한계 - 예산이 템플릿보다 23,552 B 크다. 템플릿 동기화로 15-01을 받으면 다시 재고 같은 규칙으로 내린다. 측정값이 203,776 B 이하이면 200 KiB로 돌아간다. 검증 - desktop CI env(CI=true, VITE_BUILD_ID, RELEASE_ID, VITE_COMMIT_SHA, CI_RUNNER_IMAGE): 초기 JS 229,224 B, 초기 파일 28개, 가장 큰 lazy chunk 40,038 B(예산 122,880 B).
문서 색인
docs/의 문서를 세 묶음으로 나눈다.
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
문서 안의 상태 값(COMPOSED, AVAILABLE_NOT_COMPOSED, DESIGNED_NOT_IMPLEMENTED 등)으로
확인한다. 상태 값의 뜻은 README.md의 "Support scope" 절에 있다.
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
1. 현재 계약
처음 읽을 입구 문서 6개다.
| 문서 | 정하는 것 |
|---|---|
README.md |
시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
architecture/frontend-application-foundation.md |
이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
architecture/layers.md, architecture/overview.md |
계층과 import 방향. check:architecture가 검사한다 |
architecture/starter-experience.md |
기본 라우트, 인증 모드, 기능 추가·제거 절차 |
architecture/optional-adapter-recipes.md |
선택 기능(recipe)을 넣고 빼는 절차 |
operations/ci-quality-gates.md, testing/taxonomy.md |
게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
입구 문서가 가리키는 세부 규칙:
- 계약 소유와 호환성:
architecture/contract-ownership.md,contracts/compatibility.md - 정적 배포와 런타임 설정:
architecture/static-delivery.md - 기능 개발자가 알아야 하는 양:
architecture/capability-consumer-experience.md - 운영·복구:
operations/,runbooks/ - 보안과 공급망:
security/browser-boundary.md,security/supply-chain.md - 디자인 토큰과 수동 접근성 검토:
styling/design-tokens.md,accessibility/manual-checklist.md - 버전별 변경: 템플릿 저장소의
CHANGELOG.md. 이 저장소가 받은 템플릿 변경은operations/template-sync-*.md에 동기화마다 적는다
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
|---|---|
architecture/review-ledger.json, architecture/review-evidence.md, accessibility/manual-checklist.md |
verify:documentation (FE-GATE-017) |
reviews/adapters/INVENTORY.md |
check:adapter-inventory (FE-GATE-010) |
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json |
check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json) |
2. 목표 설계
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
- 런타임 capability 결정의 정본:
architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md - 상태 원장:
architecture/browser-data-capability-completion-ledger.md - 전체 검토와 로드맵:
architecture/frontend-platform-capability-review.md,architecture/frontend-platform-implementation-roadmap.md - 포트·경계·데이터 흐름:
architecture/frontend-ports-adapters-and-boundaries.md,architecture/typescript-state-and-data-flow.md,architecture/routing-pages-and-patterns.md - API와 서버 상태:
architecture/api-contract-schema-mapper-and-server-state.md,architecture/backend-api-and-server-state-contract.md,architecture/protobuf-browser-transport-and-rest-gateway.md - 브라우저 데이터:
architecture/client-cache-and-storage.md,architecture/browser-file-and-origin-storage.md,architecture/presigned-transfer-and-image-cdn.md,architecture/server-file-capability-infrastructure.md - 실시간:
architecture/realtime-events-web-push-and-bounded-polling.md - 디자인 시스템과 테스트 전략:
styling/design-system-platform.md,testing/frontend-platform-testing-strategy.md - 결정 기록(ADR):
architecture/decisions/VD-*.md
3. 작업 이력·리뷰
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의
"Files you can delete after copying" 절에 있다.
| 경로 | 내용 |
|---|---|
superpowers/ |
과거 작업 계획과 스펙 |
reviews/ |
리뷰 결과. reviews/adapters/INVENTORY.md만 게이트가 읽는다 |