문제 docs/operations/performance-evidence.md는 다운스트림이 첫 기능 전에 예산을 정할 때 보는 유일한 자료다. 그런데 2026-09-25 측정을 그대로 적고 있다. 기준선 196,573 B(예산의 96%, 여유 약 8,200 B), "`index` 93.5 KB, `preload-helper` 28.5 KB(zod 포함)", "dynamic import chunk는 lazy다". verify:documentation은 수치를 보지 않아 통과한다. 문서와 코드 대조 (RED 대신) -298201f빌드(build-frontend.ts, classifyViteJavascript + gzipSync 기본 수준, check:bundle과 같은 계산): 초기 JS 16개 파일 202,509 B (VITE_BUILD_ID=local-build), 202,522 B(gitea-123456-1). 여유 약 2,280 B - `index` 864 B, `preload-helper` 675 B. 문서의 청크 이름별 크기가 모두 틀렸다 - 분류기(scripts/lib/classify-vite-bundle.ts)는 entry가 직접 dynamic import하는 boot·render-boot-failure도 초기로 센다. 문서 문장과 반대다 고른 방법 - 표를 현재 측정으로 바꾸고 측정 커밋(298201f)과 빌드 ID 조건을 적는다. - 청크 이름 대신 출처별(react-dom·react-router·zod·@tanstack·react· 템플릿 src) 크기를 적는다. sourcemap 빌드에서 minify 바이트를 원래 모듈에 나눠 붙이고 묶음마다 gzip했다. rolldown이 공용 청크에 모듈 하나의 이름을 붙여서 청크 이름으로 판단하면 엉뚱한 곳을 줄이게 된다는 설명을 둔다. - 15-01 뒤 기능 하나의 증가량(참조 모양 +650~750 B,298201f커밋 측정)과 그 상한 테스트를 적는다. 다운스트림이 "몇 개 더 들어가나"를 바로 본다. - 분류 규칙 문장을 분류기와 맞춘다. 버린 대안 - check:bundle이 bundle.json에 출처별 합계를 남기게 자동화: 빌드마다 sourcemap 빌드가 한 번 더 필요하다. 리뷰도 "가능하면"으로 적었고, 문서 수치를 맞추는 이번 범위를 넘는다. 위험·한계 - 15-01 커밋 본문의 202,361 B와 이번 측정이 148 B 다르다. 같은 커밋의 빌드 차이(빌드 정보·ID)로 보이나 원인은 확인하지 않았다. - 출처별 표는 sourcemap 빌드(VITE_BUILD_ID=gitea-123456-1)에서 쟀다. sourceMappingURL 주석은 빼고 셌다. - production 프로필 빌드와 pnpm 경로의 check:bundle(generate-supply-chain이 pnpm list를 부른다)은 돌리지 않았다. 검증 - verify-documentation-readiness: PASS_SCOPED - 다른 문서에 옛 수치(196,573, 96%, 8,200) 없음(git grep) Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-02
문서 색인
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
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
|---|---|
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만 게이트가 읽는다 |
../SPEC.md, ../tasks/ |
2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다 |