docs(improvement): 리뷰·수정·리팩터링의 기준이 되는 개선 작업 매뉴얼을 둔다 #6

Closed
donghyeon.kang wants to merge 10 commits from docs/improvement-manual into main
13 changed files with 1626 additions and 1 deletions
+5 -1
View File
@@ -1,5 +1,9 @@
# CLAUDE.md
## 개선 작업 기준
리뷰·결함 수정·리팩터링·성능 최적화·구조 변경·테스트 구조 개선은 [`docs/improvement/`](docs/improvement/README.md)를 기준으로 한다. 작업 종류별 절차, 검증 위치와 merge 판정 방법, 결정 기록, 세션 분업, 반복 결함 패턴이 거기 있다. 리뷰 판정 규칙의 정본은 아래 「리뷰 기준」이고, 매뉴얼은 그것을 가리킨다.
## 리뷰 기준 (모든 리뷰에 적용)
이 repo를 리뷰할 때는 전체 리뷰든 모듈·PR·diff 리뷰든 [`docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`](docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md)를 기준으로 한다.
@@ -20,7 +24,7 @@
### 전체 리뷰 절차
1. 기준 커밋과 가이드 0.1절 전제 표를 먼저 고정한다.
2. 게이트를 직접 실행하고 결과를 기록한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`, `verify:documentation`, `check:adapter-inventory`, `check:ci`.
2. 게이트를 직접 실행하고 결과를 기록한다. `config/ci/gates.json`의 merge 단계 `gateIds` 전부(지금 14개)를 workflow와 같은 env(`CI=true`, `VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE`)로 `corepack pnpm ci:gate -- FE-GATE-0NN` 하나씩 돌린다. documentation 단계의 `verify:documentation`(FE-GATE-017)은 따로 돌린다. 명령 목록을 여기 손으로 적지 않는다(방법은 `docs/improvement/07-verification-gates.md` 3절).
3. 영역별로 서브에이전트를 병렬로 띄운다. 영역 분할은 가장 최근 `docs/reviews/*-maturity-review/README.md`의 영역 표를 재사용한다.
4. 각 에이전트는 `docs/reviews/<YYYY-MM-DD>-maturity-review/NN-<영역>.md`에 결과를 쓴다.
5. 오케스트레이터는 High 이상 발견을 코드에서 직접 재확인한 뒤 같은 폴더의 `README.md`에 범위(36.1), 28개 관점 판정표(36.2), 최종 요약(36.5), 발견 색인을 쓴다.
+1
View File
@@ -30,6 +30,7 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어
입구 문서가 가리키는 세부 규칙:
- 새 기능 추가 매뉴얼(작업 순서, 단계별 판단 기준, `create:feature`): [`manual/`](manual/), [`manual/reference/`](manual/reference/). 한국어다
- 개선 작업 매뉴얼(리뷰·결함 수정·리팩터링·성능 최적화·구조 변경·테스트 구조 개선의 절차와 기준, 반복 결함 패턴): [`improvement/`](improvement/). 한국어다
- 규모 설계(구조·소유·실행·트래픽·오류·검증·텔레메트리·릴리스 일관성)와 코드 주석 `scale-architecture.md §N`의 근거: [`architecture/scale-architecture.md`](architecture/scale-architecture.md). 절마다 현재 계약인지 기록만인지 머리말 표에 적었다
- 계약 소유와 호환성: [`architecture/contract-ownership.md`](architecture/contract-ownership.md), [`contracts/compatibility.md`](contracts/compatibility.md)
- 짝 백엔드 Envelope 판정과 쓰기 전 거절 표(지금 실행 규칙, `src/adapters/http/backend-envelope.ts`의 근거): [`architecture/backend-api-and-server-state-contract.md`](architecture/backend-api-and-server-state-contract.md) 4.1·6·6.1절. 기준 커밋은 [`../config/contracts/backend-contract-pin.json`](../config/contracts/backend-contract-pin.json). 같은 문서의 나머지 절은 목표 설계다
+252
View File
@@ -0,0 +1,252 @@
# 01. 작업 종류별 절차
## 핵심
개선 작업은 여섯 종류다. 리뷰, 결함 수정, 리팩터링, 성능 최적화, 구조 변경, 테스트 구조 개선.
종류마다 **시작 조건 → 단계 → 산출물 → 완료 기준**을 같은 틀로 적는다. 시작 조건이 안 맞으면 다른 종류의 작업이다.
종류를 고르는 기준은 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"다.
| 질문 | 답 | 작업 |
| --- | --- | --- |
| 아직 무엇이 틀렸는지 모른다 | 찾는다 | 리뷰 |
| 계약과 다른 동작이 확인됐다 | 동작을 계약에 맞춘다 | 결함 수정 |
| 동작은 맞는데 구조 비용이 크다 | 동작을 그대로 두고 모양을 바꾼다 | 리팩터링 |
| 숫자로 잰 비용이 크다 | 같은 동작을 더 싸게 | 성능 최적화 |
| 최상위 폴더·adapter 그룹·기능 폴더·import 규칙이 바뀐다 | 경계를 바꾼다 | 구조 변경 |
| 테스트가 주장을 증명하지 못하거나 가끔 떨어진다 | 테스트를 고친다 | 테스트 구조 개선 |
## 0. 모든 작업의 공통 단계
1. **기준 커밋을 고정한다.** `git rev-parse HEAD`를 산출물 첫머리에 적는다. 리뷰 문서는 모두 기준 커밋으로
시작한다(`CLAUDE.md` 26줄, 1105 README 머리말).
2. **이전 기록을 읽는다.** 가장 최근 리뷰 README의 「결정이 필요한 것」「조치」「남은 문제」 절과 08장 색인을 읽는다.
이미 정한 것을 다시 묻지 않는다(08장 3절).
3. **위험을 정한다.** 위험은 파일 수가 아니라 바뀌는 경계로 정한다. 사용자 데이터(결과 불명 쓰기, OPFS 개인 파일),
공개 포트, merge 게이트, 짝 백엔드 계약을 건드리면 높다. 높으면 설계와 대안을 먼저 적는다(가이드 41절).
4. **스킬을 고른다.** 소유자 규칙이다: 리뷰·수정에 스킬을 쓴다(2026-11-03~05 사용자 지시, 08장 표 O-3). 아래 표에서
고른다.
5. **격리된 곳에서 일한다.** 자기 worktree와 브랜치를 쓴다. 리뷰어는 코드를 고치지 않는다. 의심 결함은 임시
테스트로 확인하고 그 코드는 리뷰 문서나 scratchpad에만 남긴다(`CLAUDE.md` 15줄).
6. **무거운 실행 위치를 지킨다.** 테스트·게이트·빌드는 노트북에서 돌리지 않는다(07장 7절 「소유자 환경」).
7. **보고 전에 검증한다.** 돌리지 못한 검증은 이유와 함께 "확인" 줄에 적는다. 돌린 것처럼 쓰지 않는다.
### 스킬 고르기
스킬을 불렀다는 사실보다 **그 스킬의 기준으로 무엇을 봤는지**가 증거다. 리뷰어는 불러온 스킬과 적용한 기준을 리뷰
문서 「범위」 절에 한 줄씩 적는다 **[제안]** — 지난 다섯 라운드의 리뷰 문서에는 스킬 기록이 없다.
| 작업 | 절차 스킬 | 영역 스킬(바뀌는 경계에 맞춰) |
| --- | --- | --- |
| 리뷰 | `superpowers:requesting-code-review` | `clean-architecture`, `codebase-design`, `api-and-interface-design`, `security-and-hardening`, `performance-optimization`, `playwright-best-practices`, `ci-cd-and-automation`, `frontend-ui-engineering`, `documentation-and-adrs`, `doubt-driven-development` |
| 리뷰 결과를 받아 고칠 때 | `superpowers:receiving-code-review` | — |
| 결함 수정 | `superpowers:systematic-debugging` → `superpowers:test-driven-development` | 바뀌는 경계의 영역 스킬 |
| 리팩터링 | `refactor`, `codebase-design` | `clean-architecture`, `vercel-composition-patterns` |
| 성능 최적화 | `performance-optimization` | `vercel-react-best-practices`, `web-performance-auditor`(에이전트) |
| 구조 변경 | `superpowers:brainstorming` → `superpowers:writing-plans` | `clean-architecture` |
| 테스트 구조 개선 | `superpowers:test-driven-development` | `playwright-best-practices` |
| 문서·결정 기록 | `documentation-and-adrs` | — |
| 완료 주장 전 | `superpowers:verification-before-completion` | — |
기능 개발 단계별 스킬은 `docs/manual/01-add-a-feature.md`가 단계마다 「쓸 스킬」로 적는다. 이 표는 그 표기를 따른다.
## 1. 리뷰
**시작 조건**
- 대상이 정해졌다: 전체, 영역, PR, 또는 커밋 범위(`<base>..<head>`).
- 기준 커밋과 지난 라운드의 결정·남은 문제를 읽었다.
**단계**
전체 리뷰의 뼈대는 `CLAUDE.md` 「전체 리뷰 절차」 1~5단계다(26~30줄). 아래는 그 단계를 지난 라운드에서 겪은 대로
구체화한 것이다.
1. **범위를 고정한다.** 기준 커밋, 브랜치, 확인 시점, 노트북 worktree와 desktop checkout이 깨끗한지 적는다
(1105 README 11절 표).
2. **전제를 채운다.** 전체 리뷰면 가이드 0.1절 전제 표를 채운다. 이 repo의 고정 전제는 `CLAUDE.md` 「이 repo의
리뷰 전제」 네 줄이다. 템플릿에는 요청량·데이터량 목표가 없으므로 그 칸은 "기능 수 증가 축과 lab·번들 예산으로
판정"처럼 적는다(1105 README 0절).
3. **게이트를 한 번 돌린다.** `CLAUDE.md` 2단계대로 `config/ci/gates.json`의 merge 단계 `gateIds` 14개를 workflow
env로 `ci:gate`를 통해 돌리고, `verify:documentation`을 따로 돌린다(07장 3절). 예전에는 2단계가 명령 11개를 손으로
적었고, 그 목록만 돌려 실제 러너에서 항상 실패하는 게이트 두 개를 놓친 적이 있다(1103 README 10.5절 마지막 행,
1105/12-03).
4. **결과를 함께 읽는다.** 게이트 출력과 `artifacts/`·`dist/`·`test-results/`를 읽기 전용 사본으로 떠 두고, 모든
리뷰어가 그 사본을 읽는다. 리뷰어마다 따로 돌리지 않는다(09장 4절).
5. **영역을 나눈다.** 가장 최근 리뷰 README의 영역 표를 다시 쓴다. 지금은 16개 영역이다(1103 README 10.2절,
1105 README 11.2절). 영역마다 서브에이전트나 하위 세션 하나(09장).
6. **영역을 읽는다.** 영역 문서는 「지난 발견 재판정」부터 쓴다. 지난 라운드가 "고침"이라고 한 것도 코드로 다시
본다. 4라운드는 1103 조치의 "고침" 13건을 "일부"로 정정했다(1105 README 3.1절).
7. **더 필요한 실험은 목록으로 낸다.** 리뷰어가 직접 돌리지 않는다. 총괄이 모아 같은 명령은 한 번만, 실험마다
작업 폴더를 되돌리며 일괄로 돌린다(09장 4절).
8. **발견을 02장 형식으로 적는다.** 같은 결함을 두 영역이 적으면 색인에서 하나로 합치고 「합친 중복」 표에
남긴다(1105 README 11.3절).
9. **총괄이 다시 확인한다.** High 이상과 새 P1은 총괄이 코드를 직접 읽거나 실행해 확인하고, 재확인 칸에 그 사실을
적는다(`CLAUDE.md` 30줄, 1105 README 2.2절 「재확인」 칸).
10. **README를 쓴다.** 02장 6절 형식. 총괄 자신의 실수도 적는다(1103 README 10.5절, 1105 README 11.5절).
PR·diff 리뷰는 3·4·5단계를 줄인다. 바뀐 파일의 영역만 읽고, 그 diff가 건드린 게이트만 돌린다. 판정 체계와 발견
형식은 같다.
**산출물**
- 전체 리뷰: `docs/reviews/<YYYY-MM-DD>-maturity-review/README.md`와 영역 문서 `NN-<영역>.md`(`CLAUDE.md` 29줄).
- 리뷰 문서는 리뷰 시점 기록이다. 고친 뒤에도 영역 문서를 고치지 않는다. 처리 결과는 같은 README의 「조치」 절에
적는다(1103 README 14절). 틀린 문장이 남아도 리뷰 기록은 고치지 않고, 현재 문서(CHANGELOG 등)에서 바로잡는다
(1103 README 14.7절 끝).
**완료 기준**
- 모든 발견이 02장 형식이고 성격·심각도·우선순위·통제·증거가 따로 적혀 있다.
- 지난 라운드 발견 전부의 지금 상태가 표 하나에 있다(1105 README 13절).
- 미검증 목록과 확인 방법이 있다.
- 결정이 필요한 항목마다 선택지와 결정할 사람이 있다(1105 README 7절).
- 리뷰 중 코드를 고치지 않았고, 끝에 desktop checkout의 `git status`가 비었다.
## 2. 결함 수정
**시작 조건**
- 리뷰 문서의 발견 ID가 있다. 발견 없이 고치면 그 고침이 무엇을 막는지 아무도 모른다.
- 그 발견의 「완료 기준」 칸을 읽었다. 완료 기준의 기준은 그 칸이다(`SPEC.md` 13줄).
**단계**
1. **재현 테스트를 먼저 쓴다(RED).** 동작을 바꾸는 수정은 재현 테스트가 먼저 실패하고, 고친 뒤 통과한다. 브라우저
없이 재현할 수 없으면 fake·fixture로 조건을 만든다(`SPEC.md` 29줄).
2. **검출력을 확인한다.** 테스트 검출력이 문제였던 발견(변이 생존)은 리뷰에 적힌 변이를 다시 넣어 새 테스트가
실패하는지 본다(`SPEC.md` 30줄).
3. **고친다(GREEN).** 공개 포트는 추가만 한다. 기존 시그니처를 깨야 하면 결정 표에 적는다(`SPEC.md` 35줄). 공용
로직은 `src/adapters/platform/` 또는 `src/contracts/`에 둔다. 새 파일 단위 예외를 만들지 않는다(`SPEC.md` 34줄).
4. **수정이 새로 가정하는 것을 적는다.** 커밋 본문 「위험·한계」에 쓴다. 4라운드 새 발견의 상당수가 지난 수정에서
나왔고, 수정마다 이 질문을 하는 단계가 없었다(1105 README 6절 원인 5).
5. **템플릿 원래 상태 밖에서도 확인한다.** 기능 하나를 더한 상태, 예제 기능을 지운 상태, 입력이 셋 이상인 상태로
한 번씩 돌린다. 템플릿 원래 상태나 작은 입력으로만 확인한 수정이 다시 결함이 됐다(1105 README 6절 원인 1,
부록 P-02).
6. **커밋한다.** 논리적 변경 하나에 커밋 하나, 커밋 메시지에 발견 ID, 그 작업이 바꾼 파일만 스테이징한다(`SPEC.md`
36줄, 08장 5절).
7. **빠른 게이트를 돌린다.** 작업마다 `SPEC.md` 31줄의 8개, 레인이 끝날 때와 통합 때는 32줄의 5개를 더 돌린다(07장
2절).
8. **adapter 파일을 더하거나 옮기면** `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다(`SPEC.md` 33줄).
**산출물**
- 커밋(`Refs:` 꼬리말에 발견 ID, 08장 5절).
- 리뷰 README의 「조치」 절: 방법, 결정, 통합에서 생긴 것, 발견별 상태, 검증, 남은 문제(1103 README 14.1~14.7절
구성).
- CHANGELOG 미출시 절의 행.
**완료 기준**
- 발견의 「완료 기준」 칸을 관찰했다.
- 가이드 35.6절의 다섯 연결이 있다: 원래 위험, 바꾼 코드, 그 위험을 잡는 검증, 검증한 버전·환경·결과, 남은 제한.
- 발견별 상태가 「고침 / 일부 / 결정 대기」 중 하나다. 「일부」와 「결정 대기」는 남은 것과 이유를 적는다(1103 README
14.4절). 「결정 대기」 외에는 남기지 않는다(09장 5절).
- merge 판정이 필요하면 07장 3절 방법으로 14개를 통과했다.
## 3. 리팩터링
**시작 조건**
- 동작이 맞다. 바꾸려는 이유가 이해 비용·변경 비용이다(가이드 4·9·22·23절).
- 지켜야 할 동작·타입·실패·진단 계약을 적을 수 있다. 적을 수 없으면 리팩터링이 아니라 설계 변경이다.
**단계**
1. **보존 조건을 먼저 적는다.** 가이드 36.3절 「단순화의 보존 조건」, 39.9절.
2. **기존 테스트가 그 조건을 지키는지 본다.** 못 지키면 테스트부터 더한다(5절이 아니라 이 작업 안에서).
3. **바꾼다.** 이 repo의 고정 전제를 지킨다.
- 소비자 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이다. 지우지 않는다(`CLAUDE.md` 19줄).
- 갈라진 중복 복사본은 하나로 합친다(같은 줄, 부록 P-14).
- adapter 배럴(`src/adapters/*/index.ts`)이 공개 경계다. 배럴 밖으로 공개 표면을 늘리지 않는다(`CLAUDE.md` 20줄).
4. **같은 테스트가 그대로 통과한다.** 테스트를 고쳐야 통과하면 동작이 바뀐 것이다. 결함 수정이나 설계 변경으로
다시 분류한다.
**산출물**
- `refactor(<scope>): ...` 커밋. 본문에 보존 조건과 버린 대안(커밋 규칙 3.3절).
**완료 기준**
- 테스트 변경 없이 빠른 게이트 8개가 통과한다.
- 줄어든 이해 비용을 한 문장으로 말할 수 있다(읽을 파일 수, 알아야 할 규약 수 등).
## 4. 성능 최적화
**시작 조건**
- 같은 조건에서 두 번 이상 잰 숫자가 있고, 예산을 넘거나 회귀했다(06장 2절).
- 그 숫자를 만든 측정 조건(위치·부하·반복 수·빌드)을 안다.
**단계**
1. 기준선을 06장 3절 조건으로 다시 잰다. 예전 측정값을 기준선으로 쓰지 않는다.
2. 원인을 좁힌다. 무엇이 비용을 만드는지 네트워크 waterfall·청크 목록·trace로 확인한다.
3. 바꾼다. 초기 JS 예산·초기 파일 수 상한·lab 예산을 함께 본다. 하나를 줄이며 다른 하나를 넘기지 않는다(06장 4절).
4. 같은 조건으로 다시 잰다. 대조군(바꾸기 전 커밋)을 같은 세션에서 함께 잰다.
5. 기준선 파일을 고쳐야 하면 06장 5절 절차를 따른다.
**산출물**
- 전후 숫자와 측정 조건(06장 3절 항목 전부). `perf(<scope>): ...` 커밋.
**완료 기준**
- `check:bundle`(FE-GATE-012)과 lab 게이트(`test:performance`, FE-GATE-026)가 통과한다.
- 전후 차이가 측정 잡음보다 크다. 잡음 크기를 함께 적는다.
## 5. 구조 변경
**시작 조건**
- 최상위 `src/` 폴더, adapter 그룹, 기능·context 경계, import 규칙 중 하나가 바뀐다.
**단계**
1. 설계와 대안을 먼저 적는다(`superpowers:brainstorming` → `superpowers:writing-plans`). 가이드 41절의 일곱 질문.
2. 03장의 구조 기준을 확인한다. 특히 새 파일 단위 kernel 예외를 만들지 않는다(`CLAUDE.md` 21줄).
3. 규칙과 문서를 코드와 같은 커밋에서 바꾼다.
- import 규칙: `.dependency-cruiser.json`.
- 최상위 폴더: `docs/architecture/layers.md` 표 한 행. 같은 설명을 루트 `README.md`, `docs/architecture/overview.md`,
`docs/architecture/frontend-application-foundation.md`에도 그대로 적어야 `verify:documentation`이 통과한다
(`scripts/verify-documentation-readiness.ts` 101~152줄).
- adapter 파일: `docs/reviews/adapters/INVENTORY.md`.
4. 제거 드릴을 돌린다. 지울 수 있는 단위(참조 기능, recipe, runtime)가 바뀌면 FE-GATE-020의 드릴이 그 변화를 안다
(03장 6절).
**산출물**
- 설계 문서(커밋 범위가 크면 `docs/superpowers/plans/`), 코드·규칙·문서를 함께 바꾼 커밋.
**완료 기준**
- `check:architecture`, `check:adapter-inventory`, `verify:documentation`, FE-GATE-020이 통과한다.
## 6. 테스트 구조 개선
**시작 조건**
- 테스트가 주장을 증명하지 못한다(변이가 살아남는다, 템플릿 원래 상태만 본다). 또는 가끔 떨어진다.
**단계**
1. 가끔 떨어지는 테스트는 05장 5절 절차로 원인을 찾는다. 재시도·timeout 늘리기·worker 줄이기로 덮지 않는다.
2. 테스트 위치를 `docs/testing/taxonomy.md`의 층 기준으로 정한다. 프레임워크가 아니라 필요한 실행 환경이 층을
정한다(taxonomy 85~99줄).
3. 검출력은 변이로 확인한다. 고친 테스트가 원래 결함 변이를 잡는지 본다(`SPEC.md` 30줄).
4. 바뀐 테스트가 속한 게이트를 돌린다. 브라우저 테스트는 같은 조건에서 반복 실행 결과를 함께 적는다(05장 5절).
**산출물**
- `test(<scope>): ...` 또는 `fix(test): ...` 커밋. 본문에 원인, 결정적 재현 방법, 반복 실행 결과.
**완료 기준**
- 변이 또는 결정적 재현이 고친 뒤 기대대로 실패·통과한다.
- 반복 실행에서 실패 0이다. 횟수를 적는다(1103/11-10은 고친 뒤 30회 반복, 660/660 통과).
## 지금 이해하면 되는 것
- 작업 종류는 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"로 고른다.
- 결함 수정은 RED 먼저, 발견 ID와 함께, 템플릿 원래 상태 밖에서도 확인한다.
- 리뷰는 코드를 고치지 않고, 게이트는 한 번 돌려 모두가 함께 읽는다.
+172
View File
@@ -0,0 +1,172 @@
# 02. 리뷰 기준
## 핵심
리뷰의 규칙은 `CLAUDE.md` 「리뷰 기준」(7~30줄)과 가이드가 정한다. 이 장은 그 규칙을 **이 repo의 경로·게이트·지난
결함으로 바꿔** 적는다. 무엇을 결함으로 보는지, 등급을 어떻게 매기는지, 28개 관점마다 어디를 보는지, 리뷰 문서를 어떤
모양으로 쓰는지.
```text
발견 하나 = 항목 하나 (관련 관점 번호를 모두 붙인다, 가이드 0.3절)
├─ 성격 확인된 결함 / 구조적 위험 / 미검증 / 개선 제안 (가이드 35.1절)
├─ 심각도 Critical / High / Medium / Low (35.2절)
├─ 우선순위 P0~P3 (35.3절)
├─ 통제 M0~M4, 확인 못 했으면 「미확인」(M0 아님) (35.4절)
└─ 증거 E0~E4 (35.5절)
```
## 1. 결함으로 보는 것
결함은 **이 repo가 스스로 한 약속**을 어기는 것이다. 약속은 다음에 있다.
| 약속 | 어디에 |
| --- | --- |
| 지원 범위와 상태 값 | 루트 `README.md` 「Support scope」 |
| 현재 계약 | `docs/README.md` §1이 링크한 문서 |
| 게이트가 지키는 것 | `config/ci/gates.json`과 각 검사 스크립트 |
| 생성 명령으로 기능을 더하면 템플릿 파일을 고치지 않고 merge를 통과한다 | `docs/manual/README.md` 6줄, `docs/manual/reference/create-feature.md` |
| 지울 수 있다고 한 것은 지워도 게이트가 통과한다 | 루트 `README.md` 「Files you can delete after copying」, FE-GATE-020 |
| 짝 백엔드와 맞춘 계약 | `docs/architecture/backend-api-and-server-state-contract.md` 4.1·6·6.1절, `config/contracts/backend-contract-pin.json` |
결함으로 보지 않는 것(`CLAUDE.md` 「이 repo의 리뷰 전제」, 가이드 0.1절 「지원·비지원」):
- 소비자 없는 코드와 빈 레지스트리(다운스트림용 확장 지점).
- 지원 범위 밖이라고 적힌 기능이 없는 것(예: SSR, bulk `results`). 없는 기능을 결함으로 세지 않는다.
- 서버 메모리 상태·다중 인스턴스 경쟁. 실행 형태가 브라우저 SPA라 적용하지 않는다. 탭 사이 경쟁은 본다.
- 인터페이스가 많다, kernel이 크다는 사실만으로(가이드 35.2절 끝 문단).
헷갈리는 경우:
| 경우 | 판정 | 예 |
| --- | --- | --- |
| 게이트가 코드와 무관하게 항상 실패하거나, 실패 이유를 숨긴다 | 결함. 사용자 피해가 없으면 Medium, merge·release를 막으면 P1 | 1103/02-06, 1105/12-01, 1105/13-01 |
| 게이트가 PASS인데 그 뒤 단계가 실패한다 | 결함(검사가 거짓 PASS를 낸다) | 1105/12-01, 1103/11-04 |
| 문서 문장이 코드와 다르다 | 결함. 코드가 맞다. 문장이 사용자를 틀린 행동으로 이끌면 등급을 올린다 | 1103/14-02(틀린 이행 안내) |
| 같은 사실을 여러 곳에 손으로 적었고 아직 같다 | 구조적 위험 | 1103 README 5절 원인 4 |
| 같은 사실의 손 사본이 이미 서로 다르다 | 확인된 결함 | 1105/01-02 |
| 수정이 템플릿 원래 상태에서만 맞다 | 결함. 지원 구성(기능 추가·예제 제거)에서 재현하면 확인된 결함 | 1105/09-01 |
## 2. 심각도와 우선순위 — 이 repo의 판정 예
가이드 35.2·35.3절을 지난 라운드가 이렇게 적용했다. 같은 모양이면 같은 등급을 준다. 등급을 영역 제안과 다르게
매기면 README 「심각도 조정」 표에 이유를 남긴다(1103 README 2.3절, 1105 README 2.4절).
| 등급 | 이 repo의 예 |
| --- | --- |
| High·P1 | 결과 불명 쓰기를 키 없이 다시 보내 같은 항목이 둘 생긴다(0929/03-03 상향, 가이드 35.2절 High 예시와 같은 모양). 짝 백엔드의 업무 거절이 모든 쓰기에서 결과 불명이 되어 폼이 막힌다(1103/03-01). 두 템플릿을 짝으로 쓰면 업로드가 연결되지 않는다(1103/01-01) |
| Medium·P1 | 사용자 피해 없이 merge·release 게이트가 틀린 답을 내거나 이유를 숨긴다(1103/02-06, 1103/12-01, 1103/15-01, 1105/09-01, 1105/12-01, 1105/13-01). "생성 명령으로 빠른 출시"라는 핵심 약속을 깨는 것도 여기다 |
| Medium·P2 | 위험한 경로가 남았지만 템플릿이 그리는 경로는 막고, 제품이 직접 hook을 부를 때만 닿는다(0929/03-03 남은 부분) |
| Low·P3 | 낡은 문장, 이름, 작은 진단 누락 |
- **P1의 기준:** 도입·출시·확대 전에 해결해야 하는 것(가이드 35.3절). 이 repo에서는 merge 게이트 14개를 막는 것과,
지원 구성에서 짝 백엔드와 쓰는 기본 경로를 막는 것이다.
- **복제 범위를 함께 적는다.** 다운스트림 둘(tech-log, memento)이 그대로 복제하는 기본값이면 그 사실을 적는다(가이드
35.2절 「다음 정보를 함께 적는다」).
## 3. 증거 규칙
- **현재 커밋에서 찾는다.** README와 설계 문서는 주장이다. 근거는 코드·설정·실행 결과다(`CLAUDE.md` 14줄, 가이드
34.1절). 지난 리뷰의 실행 결과를 현재 증거로 쓰지 않는다. 다른 세션이 같은 커밋에서 낸 결과도 가져다 쓰지 않고
다시 돌린다(1105 README 11.1절 끝 문단).
- **실행 증거에는 조건을 붙인다.** 커밋, 위치(desktop), env(workflow env인지), 부하, 반복 수. 부하가 높을 때의 실패는
따로 표시한다(1103 README 10.4절).
- **desktop에 workflow env를 준 실행은 실제 러너가 아니다.** 실제 Gitea 러너는 꺼져 있다. 그 사실을 미검증에 적는다
(1105 README 8절 첫 행). 이 실행의 증거 수준은 E2~E3이고, 「실제 CI 미검증」을 함께 적는다.
- **"오케스트레이터 확인"의 뜻을 지킨다.** 재확인 칸에 이 말을 쓰면 총괄이 그 줄을 직접 읽었거나 직접 실행했다는
뜻이다(1103 README 2절 머리말).
- **확인하지 못한 것은 「미확인」이다.** M0(통제 부재 확인)와 다르다(`CLAUDE.md` 12줄).
## 4. 28개 관점 — 이 repo에서 볼 곳
관점의 일반 설명은 가이드 1~28절이다. 아래는 이 repo에서 먼저 볼 곳과 그 관점을 지키는 검사, 지난 대표 발견이다.
「검사」 칸이 비어 있으면 그 관점을 기계로 지키는 게이트가 없다는 뜻이다.
| # | 관점 | 이 repo에서 볼 곳 | 검사 | 지난 대표 발견 |
| --- | --- | --- | --- | --- |
| 1 | 코드 성숙도 | 판정 규칙이 모인 곳: `src/adapters/http/backend-envelope.ts`, 효과 분류, 폼 상태 | FE-GATE-002·003 | 1103/03-01 |
| 2 | 구조적 성숙도 | `docs/architecture/layers.md`, `.dependency-cruiser.json`(03장) | `check:architecture`(FE-GATE-010) | 0929/12-03 |
| 3 | 변경 용이성 | 기능 하나를 더하거나 지울 때 템플릿 파일을 고쳐야 하는가 | FE-GATE-020 | 1103/12-01, 1105/09-01 |
| 4 | 인지 부하 | 기능 작성자가 알아야 할 등록 규약 수, `docs/manual/` 막힘 | | 1103 README 14.6절(매뉴얼만으로 기능 추가 재실험) |
| 5 | 위험 가시성 | 결과 불명·재전송·삭제 같은 위험이 코드와 화면에 드러나는가(가이드 29절) | | 1105/13-01, 1105/12-01 |
| 6 | 실패 성숙도 | 짝 백엔드 오류 응답의 분류, 결과 불명 처리 | FE-GATE-007 | 1105/01-01 |
| 7 | 운영 성숙도 | `docs/runbooks/`, `docs/operations/`, release job 로그 | FE-GATE-021~025 | 1105/13-01 |
| 8 | 디버깅 가능성 | 실패 메시지가 원인과 고칠 파일을 말하는가, `traceId` | | 1105/12-01 |
| 9 | 유지보수 성숙도 | 낡은 문장, CHANGELOG 미출시 절 | `verify:documentation` | 1103/14-01, 1105/14-01 |
| 10 | 테스트 성숙도 | 변이 검출, 템플릿 원래 상태 밖 입력(05장) | FE-GATE-005~009 | 1103/10-02, 1103/05-01 |
| 11 | 데이터 성숙도 | 로그아웃·계정 삭제 뒤 남는 데이터(IndexedDB, OPFS, Cache Storage) | | 1103/05-01 |
| 12 | 동시성 성숙도 | 탭 사이 경쟁, Web Locks, 같은 입력 재제출, 한 checkout 두 실행 | | 1103/05-01, 1105/12-04 |
| 13 | 확장성 | 기능 수 증가 축: 초기 JS 여유, 기능 모양 상한 | `check:scale:pr`(FE-GATE-005), FE-GATE-012 | 1105/15-02 |
| 14 | 성능 성숙도 | 06장 | FE-GATE-012·026 | 1103/15-01 |
| 15 | 보안 성숙도 | `docs/security/browser-boundary.md`, 저장 키, 401 전달, CSP | FE-GATE-013 | 1103/13-03 |
| 16 | 의존성 성숙도 | advisory, lockfile, 의존성 변경 증거 | FE-GATE-001·013 | 1103/13-03 |
| 17 | API / Contract 성숙도 | 짝 백엔드 계약 pin, 답 표, 생성기가 옮긴 사실 | FE-GATE-007, 짝 계약 대조 테스트(1103 결정 D6) | 1105/07-01, 1105/16-02 |
| 18 | 배포 성숙도 | `docs/architecture/static-delivery.md`, 호스팅 헤더, 배포 슬롯 | FE-GATE-019 | 1105/13-02 |
| 19 | 설정 성숙도 | 런타임 설정과 빌드 식별값, CI env | `verify:documentation`(runtime variables) | 1103/11-07, 1103/11-08 |
| 20 | 개발자 경험 | `create:feature`, 로컬 실행, 한 파일 테스트 실행 | | 1105/16-04 |
| 21 | Guardrail 성숙도 | 게이트가 맞는 답을 내는가, 사전 점검이 실제로 확인하는가 | `check:ci` | 1105/12-01, 1105/09-01 |
| 22 | 추상화 성숙도 | descriptor·포트가 실제 요청을 통제하는가 | | 1103/04-01 |
| 23 | 일관성 | 같은 판정을 하는 두 표가 같은가 | | 1105/01-02 |
| 24 | 네이밍 / 의미 성숙도 | 오류 code·상태 이름의 뜻 | | 1105/04-02 |
| 25 | 조직 확장성 | 기능 브랜치끼리 같은 줄 충돌, 다운스트림 동기화 비용 | | 1105/16-01 |
| 26 | Ownership 성숙도 | 규칙 `comment`의 담당·재검토 조건, 두 repo 사이 몫 | | 1105/13-02 |
| 27 | 삭제 가능성 | 참조 기능·recipe·선택 runtime 제거(03장 6절) | FE-GATE-020 | 1105/14-01 |
| 28 | 회복 가능성 | 회복 필요 응답 뒤 행동, SW 비상 경로, release rollback | FE-GATE-025 | 1105/02-02 |
## 5. 다시 판정할 때
다음 라운드 리뷰는 지난 발견 전부의 지금 상태를 표 하나로 적는다(1105 README 13절).
- 상태: 고침 / 일부 / 남음 / 결정 대기. 지난 「고침」도 코드로 다시 본다. 4라운드는 1103 조치의 「고침」 13건을
「일부」로 정정했다. 코드는 들어왔지만 완료 기준 실행이 없으면 「일부」다(가이드 35.6절, 1105 README 3.1절, 부록
P-27).
- 「일부」면 남은 부분에 새 등급을 매긴다. 남은 부분이 원래보다 좁으면 등급을 내린다(1105 README 2.3절 표).
- 지난 수정이 만든 새 결함은 새 발견으로 세고, 원인 수정 커밋을 적는다(1105 README 4절 끝 목록).
## 6. 리뷰 문서 형식
### 6.1 폴더와 ID
- 폴더: `docs/reviews/<YYYY-MM-DD>-maturity-review/`. README 하나와 영역 문서 `NN-<영역>.md`(`CLAUDE.md` 29줄).
- 발견 ID는 라운드 안에서 `NN-MM`(영역 번호-순번). 라운드 밖에서는 `MMDD/NN-MM`(가이드 36.3절).
- 총괄이 직접 찾은 발견은 관련 영역 번호를 쓰고 README 「오케스트레이터 발견」 절에 둔다(1105 README 14절).
### 6.2 README 절 순서
4라운드 README(1105)의 순서다. 가이드 36.5절 요약 일곱 항목과 36.1·36.2절을 담는다.
| 절 | 내용 |
| --- | --- |
| 머리말 | 기준 가이드, 대상 커밋, 영역 수, 실행 위치, 리뷰 중 코드를 고치지 않았다는 사실 |
| 0 평가 전제 | 가이드 0.1절 표 |
| 1 사용 결정 | 용도별 사용 가능·조건부·보류와 막는 항목(36.5-1) |
| 2 차단 항목 | 새 High, 새 P1(재확인 칸 포함), 이월 항목 중 남은 큰 것, 심각도 조정과 합침 |
| 3 물은 것에 대한 답 | 리뷰를 맡긴 쪽이 따로 물은 것 |
| 4 새 발견 건수 | 지난 라운드와 심각도·우선순위·성격별 비교 |
| 5~10 | 확인된 강점, 반복되는 원인, 결정이 필요한 것, 미검증, 개선 순서, 재검토 조건(36.5-2~7) |
| 11 리뷰 범위 | 36.1절 표, 게이트 실행 결과, 영역 분할, 합친 중복, 실행 방식과 안전 사항, 총괄 자신의 실수 |
| 12 28개 관점 판정 | 36.2절 표. 영역별 판정 문자열과 종합. 종합은 평균하지 않는다. 한 영역이라도 미충족이면 미충족(35.7절) |
| 13 지난 발견 상태 | 5절 |
| 14 오케스트레이터 발견 | 36.3절 양식 |
| 15 새 발견 색인 | 영역 문서에서 기계적으로 모은다. 손으로 옮기지 않는다 |
수정 라운드가 끝나면 같은 README에 「조치」 절을 더한다(01장 2절 산출물).
### 6.3 영역 문서 절 순서
1103·1105 영역 문서의 순서다(예: 1103 `11-tests-browser-release-scale.md`).
| 절 | 내용 |
| --- | --- |
| 0 결론 | 몇 줄 |
| 1 범위 | 36.1절. 읽은 경로, 돌린 것, 확인하지 못한 것 |
| 2 지난 발견 재판정 | 5절 |
| 3 이번 발견 | 36.3절 양식. 설계 선택이 없는 단순 결함은 선택 비교 칸을 「적용 제외」와 한 문장 이유로 |
| 4 28개 관점 판정 | 36.2절 |
| 5 설계 선택 설명 | 가이드 41절. 여러 타당한 선택지가 있는 발견만 |
| 6 실험·실행 기록 | 어디서 무엇을 돌렸나, 명령·결과 표, 미검증 목록 |
## 지금 이해하면 되는 것
- 결함은 이 repo가 스스로 한 약속(지원 범위, 현재 계약, 게이트, 생성 명령, 제거 가능성, 짝 계약)을 어기는 것이다.
- 게이트가 틀린 답을 내거나 이유를 숨기면 사용자 피해가 없어도 Medium·P1이다.
- 증거는 현재 커밋의 실행에서, 조건을 붙여서. 지난 「고침」도 다시 본다.
@@ -0,0 +1,99 @@
# 03. 폴더·모듈 구조 기준
## 핵심
폴더 구조의 규칙은 이미 코드와 게이트에 있다. 이 장은 **구조를 바꿀 때 어느 정본을 같이 고쳐야 하는지**와
**리뷰에서 구조 결함으로 볼 것과 보지 않을 것**만 적는다.
```text
src/ 최상위 9개 폴더 ── 역할: docs/architecture/layers.md 표
│ 규칙: .dependency-cruiser.json (check:architecture, FE-GATE-010)
├─ adapters/<그룹>/index.ts ── 공개 경계(배럴)
│ └─ platform/** 등 kernel 3곳만 그룹을 넘어 import 가능
├─ features/<id>/ ── 지울 수 있는 기능 하나 (제거 드릴, FE-GATE-020)
└─ contexts/, apps/ ── 기능 묶음과 배포 단위
```
## 1. 정본
| 무엇 | 정본 | 검사 |
| --- | --- | --- |
| 최상위 `src/` 폴더 9개와 각 역할 | `docs/architecture/layers.md` 7~21줄 표 | `verify:documentation`이 폴더 목록·설명 일치를 본다(`scripts/verify-documentation-readiness.ts` 101~152줄) |
| import 규칙 31개 | `.dependency-cruiser.json` `forbidden`, 설명은 `docs/architecture/layers.md` 33~75줄 | `check:architecture` |
| adapter kernel | `docs/architecture/layers.md` 77~97줄, `.dependency-cruiser.json` 253~261줄 | `check:architecture` |
| 규칙 예외의 이유·담당·재검토 조건 | 그 규칙의 `comment`(`docs/architecture/layers.md` 104~117줄) | 사람이 본다 |
| adapter 그룹의 공개 경계 | `docs/architecture/layers.md` 119줄부터, 규칙 `adapter-groups-are-reached-through-their-barrel` | `check:architecture`, 고정 fixture `tests/fixtures/architecture/dependency-graph/barrel` |
| adapter 파일 목록 | `docs/reviews/adapters/INVENTORY.md` | `check:adapter-inventory`(FE-GATE-010) |
| 공유 타입·프리미티브를 어디에 둘지 | `docs/architecture/contract-ownership.md` 「Decision rule」 | 사람이 본다 |
| 기능 폴더의 모양 | `docs/manual/01-add-a-feature.md`, `create:feature`가 만드는 파일 | FE-GATE-020의 `test:feature-scaffold` |
| 문서 묶음(현재 계약 / 목표 설계 / 작업 이력) | `docs/README.md` | `verify:documentation` |
## 2. 이 repo의 고정 전제
`CLAUDE.md` 「이 repo의 리뷰 전제」(19~22줄)를 구조 기준으로 읽으면 다음과 같다.
1. **확장 지점은 남긴다.** repo 안에 소비자가 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이다. 죽은 코드로
보고 지우지 않는다. 2026-09-16 사용자 결정 1(08장 표 O-1)이 출처다.
2. **갈라진 중복 복사본은 하나로.** 같은 일을 하는 코드가 두 벌이고 서로 달라지기 시작했으면 결함이다(부록 P-14).
합칠 곳은 kernel(`src/adapters/platform/`)이나 `src/contracts/`다(`SPEC.md` 34줄).
3. **배럴이 공개 경계다.** 그룹 바깥(`src/bootstrap`, `src/features`, `src/presentation`)은 그룹의 `index.ts`만 import한다.
배럴 폐지는 2026-09-16에 기각됐다(08장 표 O-2).
4. **kernel 예외는 셋뿐이다.** `src/adapters/platform/` 폴더 전체, `src/adapters/browser-file-storage/result.ts`,
`src/adapters/cross-context-invalidation/index.ts`. 새 파일 단위 예외를 제안하지 않는다(`CLAUDE.md` 21줄). 새 공유
프리미티브는 `src/adapters/platform/`에 넣는다. 폴더 전체가 예외라 규칙을 바꿀 필요가 없다.
5. **실행 형태는 브라우저 SPA + 정적 호스팅 + Service Worker다.** 서버 메모리 상태·다중 인스턴스 경쟁 기준은 적용하지
않는다. 탭 사이 경쟁은 적용한다(1105 README 0절).
## 3. 바꿀 때 같이 고칠 것
| 바꾸는 것 | 같은 커밋에서 고칠 것 |
| --- | --- |
| 최상위 `src/` 폴더 추가·삭제 | `docs/architecture/layers.md` 표 한 행. 같은 설명 문장을 루트 `README.md`, `docs/architecture/overview.md`, `docs/architecture/frontend-application-foundation.md`에 그대로 |
| import 규칙 추가·이름 변경 | `.dependency-cruiser.json`, `docs/architecture/layers.md` 규칙 표의 행(규칙 이름이 빠지면 `verify:documentation`이 실패) |
| 규칙 예외 | 그 규칙의 `pathNot`과 `comment`(이유·담당·재검토 조건). 파일 단위 kernel 예외는 만들지 않는다 |
| adapter 파일 추가·이동·삭제 | `docs/reviews/adapters/INVENTORY.md`(`SPEC.md` 33줄) |
| adapter 그룹 공개 표면 | 그 그룹의 `index.ts`. 2단계 `index.ts`는 공개 배럴이 아니다(예외: `storage/indexeddb`, `storage/opfs` 서브배럴) |
| 기능·context 경계 | `src/features/<id>/`와 `tests/features/<id>/`. 기능끼리, context끼리 import하지 않는다(규칙 `features-do-not-import-other-features`, `contexts-do-not-import-other-contexts`) |
| 지울 수 있는 단위(참조 기능, recipe, 선택 runtime) | 그 단위의 제거 드릴이 함께 지울 목록. 예: `scripts/test-sample-removal.ts`의 머리말 주석과 `SAMPLE_EXTRAS`(루트 `README.md` 「Files you can delete after copying」 아래 문단) |
## 4. 문서 위치
| 문서 | 둘 곳 |
| --- | --- |
| 지금 코드가 지키는 규칙 | `docs/README.md` §1 묶음. 링크하면 `verify:documentation` 범위에 든다 |
| 앞으로의 설계·결정 | §2 묶음. ADR은 `docs/architecture/decisions/` |
| 리뷰·계획·작업 추적 | §3 묶음(`docs/reviews/`, `docs/superpowers/`). 복사한 프로젝트가 지울 수 있다 |
| 새 기능 절차 | `docs/manual/` |
| 개선 작업 기준 | `docs/improvement/`(이 매뉴얼) |
| 여러 repo에 걸친 설계·공통 원칙 | repo 밖 `design-docs`. 템플릿 `docs/`에 두지 않는다(`docs/manual/README.md` 「이 폴더에 두지 않는 것」) |
- 코드·테스트·스크립트·설정은 지워도 되는 문서(`docs/reviews/`, `docs/superpowers/`, `SPEC.md`, `CLAUDE.md`, `tasks/`)를
읽지 않는다. 예외는 `docs/reviews/adapters/INVENTORY.md` 하나다. `tests/unit/deletable-history-documents.test.ts`가
검사한다. 테스트가 리뷰 문서를 열어 제거 드릴 셋을 깨뜨린 적이 있다(같은 파일 머리말).
- 현재 계약 문서는 작업 이력 문서에 기대지 않는다(`docs/manual/README.md` 68줄).
## 5. 리뷰에서 구조 결함으로 보는 것
| 결함으로 본다 | 결함으로 보지 않는다 |
| --- | --- |
| 갈라진 중복 복사본(부록 P-14) | 소비자 없는 확장 지점, 빈 레지스트리 |
| 같은 사실을 여러 곳에 손으로 다시 적는다(부록 P-03) | 인터페이스가 많다는 사실만으로(가이드 35.2절) |
| 문서가 없는 폴더·규칙을 말한다 | kernel 폴더가 크다는 사실만으로 |
| 템플릿 파일을 고쳐야 기능을 더하거나 지울 수 있다(1103 README 5절 원인 2) | 다운스트림이 쓰지 않는 선택 runtime |
| 지울 수 있다고 한 단위를 지우면 게이트가 실패한다(1105/14-01) | |
## 6. 제거 가능성
지울 수 있는 단위는 merge 게이트 FE-GATE-020의 드릴이 지켜 준다. 드릴 목록은 `config/ci/gates.json`의 FE-GATE-020
`commandIds` 다섯 개다(`test:sample-removal`, `test:feature-scaffold`, `test:optional-recipe-removal`,
`test:browser-file-storage-removal`, `test:realtime-removal`).
- 구조를 바꾸면 드릴을 돌린다. 드릴 fixture가 복사하는 파일 목록이 바뀐 구조를 아는지 본다. fixture 복사 목록에
`README.md`·`CHANGELOG.md`가 없어 드릴 넷 중 셋이 항상 실패한 적이 있다(1103/02-06).
- 드릴은 오래 걸린다. FE-GATE-020은 1,150초 안팎이다(1105 README 11.1절). desktop에서 잠금 아래 돌린다(07장 7절).
## 지금 이해하면 되는 것
- 폴더 역할은 `layers.md`, import 규칙은 `.dependency-cruiser.json`, adapter 목록은 `INVENTORY.md`가 정본이다.
- 확장 지점은 남기고, 갈라진 복사본은 합친다. 새 공유 코드는 `src/adapters/platform/`이나 `src/contracts/`로.
- 구조를 바꾸면 규칙·문서·INVENTORY를 같은 커밋에서 고치고 제거 드릴을 돌린다.
+127
View File
@@ -0,0 +1,127 @@
# 04. 코드 구조 기준
## 핵심
결함을 고치거나 리팩터링할 때 지킬 코드 기준이다. 계층·import 규칙은 03장과 게이트가 지킨다. 이 장은 **게이트가
지키지 못하고 다섯 라운드 동안 반복된 결함**을 막는 기준을 적는다.
```text
판정 규칙은 한 곳에 → 실패 분류·결과 불명·멱등 키 (2절)
실패는 드러나게 → 원인을 싣고, 멈추지 않고, 사실대로 보고 (3절)
같은 사실은 한 곳에 → repo 안 손 사본, 두 템플릿 사이 손 사본 (4절)
지우거나 바꿀 때 → 그 코드가 지키던 것을 찾는다 (5절)
설정·환경은 한 출처에서 → 빌드 설정, base path, 테스트 env (6절)
고칠 때 → 수정이 새로 가정하는 것을 적는다 (8절)
```
각 기준 끝의 `P-NN`은 부록 결함 패턴 카탈로그의 행이다. 그 행에 지난 발견 ID가 있다.
## 1. 정본
| 무엇 | 정본 |
| --- | --- |
| 계층과 import 방향 | `docs/architecture/layers.md`, `.dependency-cruiser.json`(03장) |
| 재시도 의미, 결과 불명, 인증, 업로드의 판단 기준 | `docs/manual/02-decision-tables.md` 3·4·5·7절 |
| 오류 모델, 재시도 모델, 실패 경계, trace | `scale-architecture.md §13`, `§17`, `§29`, `§30` (`docs/architecture/scale-architecture.md`) |
| 짝 백엔드 응답의 판정 표 | `src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`, 근거 문서 `docs/architecture/backend-api-and-server-state-contract.md` 6.1절 |
| 위험을 코드에 드러내는 방법 | 가이드 29절 |
| 설계 의도와 단순화의 보존 조건 | 가이드 39절 |
## 2. 판정 규칙은 한 곳에
- **실패 분류는 status 하나로 하지 않는다.** status와 code를 함께 본다. 표 밖의 값은 안전한 쪽(결과 불명)으로 둔다.
업무 거절이 결과 불명으로, 일시 오류가 무결성 실패로, rate-limit 503이 결과 불명으로 분류되는 결함이 두 라운드
다섯 영역에서 났다. P-28
- **짝 백엔드 쓰기 응답의 판정 표는 `REFUSED_BEFORE_WRITE` 하나다.** 실행 경로가 둘이어도 같은 표를 읽는다. 표를
경로마다 따로 두면 두 번째 표가 다시 갈라진다(1101 README 14.6절의 버린 대안). operation 단위 예외는 descriptor의
`commandEffect.refusedBeforeWrite` code 목록으로만 선언한다(1103 결정 D2).
- **결과 불명 쓰기를 다시 보내는 모든 입구를 함께 본다.** 재전송 버튼, hook 재제출, 실행기 재시도, poll 재시도, 업로드
재시도. 하나를 막으면 다른 입구에서 다시 나왔다. 키 없는 쓰기(`NEVER`)는 결과 불명 뒤 재전송하지 않는다. 키 있는
쓰기는 같은 키로만 다시 보낸다. P-29
- **판정 규칙의 경계를 테스트로 고정한다.** 경계 하나를 바꾸는 변이가 게이트에서 실패해야 한다(05장 3.2절). P-13
## 3. 실패는 드러나게
- **원인과 추적값을 싣는다.** 실패 객체·진단에 effect, reason, `traceId`, 어느 참여자인지를 싣는다. 서로 다른 실패를
같은 reason으로 남기지 않는다. 진단 reason은 이 repo가 소유한 닫힌 목록이고 서버 code를 그대로 넣지 않는다.
서버 code는 실패의 `AppFailure.code`에 남는다(커밋 `93782b0` 결정, 1101 README 14.6절). 한 모듈에서 고친 누락이 새 모듈에서 다시 생겼다. 새 adapter는 같은
기준으로 리뷰한다. P-33
- **오지 않을 신호를 기다리지 않는다.** 모든 대기에는 끝나는 조건(예산 소진, 마감, 취소)이 있다 **[제안]** — 지난
완료 기준(0925/04-01 "예산을 실제로 소진했을 때만 terminal")을 일반 규칙으로 올린 것이다. P-30
- **손상 한 건이 전체를 멈추지 않게 한다.** 손상 행은 건너뛰고 수를 보고한다(1101 README 14.1절 0929/05-01 행).
P-31
- **결과를 사실대로 보고한다.** 다 하지 못했으면 `COMPLETED`·`verified`·`active`를 보고하지 않는다. 상태를 읽은
시점과 보고하는 시점 사이에 다른 작업(다른 탭의 put, release)이 끼어들 수 있으면, 같은 잠금 아래에서 다시 대조하거나
끝난 뒤 한 번 더 센다(1105 README 9절 1103/05-01 행). 테스트는 객체 셋 이상으로 한다. P-32
- **실패·복구 전이 뒤 화면이 다음 행동을 남긴다.** 실패 표시에서 고친 포커스·안내 장치를 복구 성공, 확인, 진행 중
전이에도 쓴다. 페이지마다 복사하지 않고 공용 폼 hook 안에서 한다. P-38
- **확인하지 못한 판정은 `PASS`가 아니라 `UNVERIFIED`다.** 코드에 상수 `true` 판정을 두지 않는다(`SPEC.md` D-14).
## 4. 같은 사실은 한 곳에
- **repo 안:** 스키마 메타, 레지스트리 행, 허용 키 목록, 빌드 입력 목록, 저장 키를 원본(zod 스키마, descriptor,
registry)에서 뽑는다. 손으로 다시 적어야 하면 원본과 대조하는 테스트를 같이 둔다. 두 검사기가 같은 산출물을 다른
키 목록으로 읽어 merge 게이트가 항상 실패한 적이 있다(1103/12-09). P-03
- **이미 갈라진 복사본은 하나로 합친다.** 합칠 곳은 `src/adapters/platform/`(adapter 공용 메커니즘)이나
`src/contracts/`(공유 어휘)다. 갈라진 recipe port는 지우고 `src` port를 다시 내보낸다(1101 README 14.1절 0929/05-03
행). P-14
- **두 템플릿 사이:** 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 프론트에 옮길 때는 백엔드 문서만 보지
않고 **코드까지 따라간다**(백엔드 생성기, 프론트 폼까지). 판정 표를 백엔드 계약 문서만으로 정해 High를 만든 적이
있다(1103 README 10.5절 03-01 행). 옮긴 사실은 기준 커밋(`config/contracts/backend-contract-pin.json`)과 대조
테스트로 묶는다(1103 결정 D6). pin과 drift 검사는 아직 계약 문서 글자만 비교한다. 답 표 JSON과 생성기 사실은 대조
밖이다(1105/07-01, 1105/16-02). P-04
- 짝 백엔드 repo는 읽기만 한다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다(09장 1절).
## 5. 지우거나 바꿀 때
- **그 코드가 지키던 것을 찾는다.** 실행 동작만 옮기면 지운 행·테스트·분기가 지키던 규칙이 조용히 사라진다. V2
삭제 때 실행 동작 셋만 찾고, 지운 검사·테스트가 지키던 것을 놓쳤다(1103/07-01, 1103/10-04). 지우기 전에 그 코드를
읽는 테스트와 검사를 `git grep`으로 찾고, 각각이 지키던 규칙이 새 경로에도 있는지 적는다. P-23
- **이름을 바꿀 때는** 새 이름을 내고 옛 이름은 한 릴리스 동안 `@deprecated` 별칭으로 남긴다(1101 README 14.1절
16-03 행). 이름 하나가 여러 뜻을 가지거나 한 뜻이 여러 이름을 가지면 결함이다. P-37
- **확장 지점은 지우지 않는다.** 소비자 없는 코드와 빈 레지스트리는 다운스트림용이다(03장 2절).
- **공개 포트는 추가만 한다.** 깨야 하면 결정 표에 적고 BREAKING으로 커밋한다(`SPEC.md` 35줄, 08장 6절).
## 6. 설정·환경은 한 출처에서
- **같은 설정을 경로마다 다르게 읽지 않는다.** 번들, 빌드 스크립트, Service Worker 빌드가 같은 출처에서 읽는다. P-35
- **URL은 router base path를 따른다.** `/`부터 직접 조립하지 않는다. 기본 게이트가 루트 경로만 돌아 드러나지 않는다.
하위 경로 빌드 테스트로 확인한다. P-34
- **테스트가 띄우는 빌드·서버의 env는 테스트가 정한다.** workflow가 job 전체에 주는 `CI=true`와 빌드 식별값이
vitest·dev server·테스트 안 빌드로 새면 실제 CI에서만 실패한다. 테스트용 로컬 빌드 식별값은
`scripts/lib/build-environment.ts`가 한 곳에서 준다. 테스트마다 env에서 기대값을 읽는 방식은 버렸다(다음 테스트가
같은 실수를 한다). P-05
- **환경 가정은 적고, 확인하고, 없으면 이유를 말하며 실패한다.** 글꼴, user namespace, 옆 checkout(07장 5·6절). P-08
## 7. 동시성
- 여러 탭이 같은 저장소·구독·잠금을 건드리는 경로는 Web Locks로 직렬화하거나, 잠금 없이도 안전한 이유를 적는다
(`SPEC.md` D-3·D-4). 잠금을 기다리는 작업에는 abort와 상한이 있다. P-36
- 실행 형태가 브라우저 SPA라 서버 다중 인스턴스 경쟁은 보지 않는다. 탭 사이 경쟁은 본다(02장 1절).
## 8. 확장 지점과 경계
- **제품마다 다른 것은 제품 소유 파일에 둔다.** 제품이 템플릿 소유 파일을 고쳐야 하면 결함이다. 동기화마다 같은 파일이
충돌한다. 제품 소유 자리의 예: `src/bootstrap/product-composition.ts`, `src/contracts/product-contracts.ts`,
`config/ci/product-gates.json`. 효과는 다음 동기화 충돌 수로 잰다(1101 README 5절). P-39
- **경계 예외는 실제 쓰임만큼만 연다.** 예외의 이유·담당·재검토 조건을 규칙의 `comment`에 적는다. kernel 폴더에는 공유
메커니즘만 둔다(03장 2절). P-40
- **두 모듈이 이어지는 곳을 지나는 테스트를 둔다.** 모듈마다 단위 테스트가 있어도, 한쪽이 보내는 결과를 다른 쪽이 다른
뜻으로 받는 결함은 연결 지점에서만 보인다. P-41
## 9. 고칠 때 — 수정이 새로 가정하는 것
4라운드 새 발견 48건 중 22건의 원인이 지난 수정이었다(1105 README 4절 끝). 수정 커밋마다 다음을 본문 「위험·한계」에
적는다.
1. 이 변경이 새로 가정하는 상태(빈 제품 파일, CI env 없음, 객체 하나, 기능 0개 등).
2. 그 가정이 깨지는 지원 구성에서 한 번 돌렸는가(01장 2절 5단계).
3. 이 변경이 다른 검사를 약하게 했는가. 예: 경로를 백틱 밖으로 옮겨 문서 검사를 피한 수정이 그 경로를 검사 밖으로
냈다(1105/14-03). 위험을 커밋 본문에 적고도 테스트하지 않아 다운스트림 게이트가 항상 실패한 수정도 있다
(1105/09-01, 수정 커밋 `235143c`). P-26
## 지금 이해하면 되는 것
- 판정 규칙은 한 곳, 표 밖은 안전한 쪽. 결과 불명 쓰기의 모든 재전송 입구를 함께 본다.
- 같은 사실은 원본에서 뽑거나 대조 테스트로 묶는다. 짝 백엔드 사실은 코드까지 따라간다.
- 수정은 새로 가정하는 것을 적고, 그 가정이 깨지는 구성에서 돌려 본다.
+140
View File
@@ -0,0 +1,140 @@
# 05. 테스트 구조 기준
## 핵심
테스트는 **결함을 막는지**로 평가한다. 테스트가 있다는 사실, 커버리지 숫자는 근거가 아니다. 이 repo의 테스트 결함은
다섯 라운드 동안 같은 모양으로 반복됐다.
```text
결함을 고쳐도·규칙을 지워도 통과한다 → 변이로 확인한다 (3절)
템플릿 원래 상태·작은 입력에서만 맞다 → 기능 추가·예제 제거·입력 3개 이상으로도 돈다 (3절)
속도·부하·브라우저 추정에 기댄다 → 결정적 재현으로 원인을 찾는다 (5절)
고정 경로·포트·로컬 생성물에 기댄다 → 깨끗한 clone·한 checkout 두 실행으로 확인한다 (4절)
```
## 1. 정본
| 무엇 | 정본 |
| --- | --- |
| 테스트 층, 명령, 실행 환경, 층을 정하는 기준 | `docs/testing/taxonomy.md` |
| 넓은 테스트 설계, flaky 정책, 금지 패턴 | `docs/testing/frontend-platform-testing-strategy.md` 16.5절(1183~1196줄), 19절(1399~1418줄). 목표 설계 문서라 지금 코드와 다른 곳이 있다(예: 15절 디렉터리 구조). 다르면 코드가 맞다 |
| Vitest 수집 범위, `.only` 금지, 전역 timeout | `vitest.config.ts` |
| Vitest 실행 runner(Node 버전, `NODE_ENV`, 생성물) | `scripts/run-vitest.ts` |
| skip·todo를 남긴 실행의 실패 | `scripts/lib/no-skipped-tests-reporter.ts` |
| Playwright skip·fixme의 quarantine 조건, `forbidOnly` | `scripts/check-test-evidence.ts` |
| 테스트 공통 대기 기한 | `tests/setup.ts` 5~13줄 |
| 모든 테스트 파일이 어떤 게이트에서 도는가 | `check:ci`, 예외 목록 `config/ci/ungated-tests.json` |
| 지워도 되는 문서를 테스트가 읽지 않는다 | `tests/unit/deletable-history-documents.test.ts` |
## 2. 테스트를 어디에 둘까
`docs/testing/taxonomy.md` 85~99줄이 기준이다. **프레임워크가 아니라 필요한 실행 환경**이 층을 정한다.
| 필요한 것 | 둘 곳 | 명령 |
| --- | --- | --- |
| Node만(도메인·정책·순수 함수, 스크립트의 짧은 CLI 계약) | `tests/unit` | `test:unit` |
| 재사용 capability의 소비자 계약 | `tests/contract` | `test:contract` |
| React·hook·UI 동작 | `tests/component` | `test:component` |
| HTTP/MSW, IndexedDB, 조립된 경계, 오래 사는 자식 프로세스 | `tests/integration` | `test:integration` |
| systemd·bubblewrap·cgroup v2 | `tests/system` | `test:system`(FE-GATE-013) |
| 실제 브라우저 3엔진 | `tests/e2e`, `tests/browser-capabilities`, `tests/visual`, `tests/storybook` | FE-GATE-008·009 |
| 한 기능의 테스트 | `tests/features/<id>/` | 기능 폴더와 함께 지워진다 |
- 스크립트 테스트가 자식 프로세스를 띄우면 그 suite가 자기 timeout을 선언한다. 전역 timeout(`vitest.config.ts`의
`testTimeout`)을 올리지 않는다(taxonomy 95~99줄).
- 플랫폼을 지키는 테스트는 참조 기능·스타터 화면에 묶지 않는다. 샘플을 지우면 그 테스트도 사라지거나 게이트가 깨진다.
테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(`tests/mocks/`)를 쓴다(1101 README 14.1절 0929/10-02 행, 부록 P-20).
- 기능 테스트가 지워도 되는 문서를 읽으면 제거 드릴이 깨진다(03장 4절).
## 3. 테스트가 결함을 막는지 확인하는 법
### 3.1 RED 먼저
동작을 바꾸는 수정은 재현 테스트가 먼저 실패하고, 고친 뒤 통과한다(`SPEC.md` 29줄). 커밋 본문에 RED와 GREEN을
적는다(1101 README 349줄). 이 규칙을 강제하는 게이트는 없다. 리뷰가 커밋 본문으로 확인한다.
### 3.2 변이로 검출력을 잰다
- 보호 규칙 한 줄을 지우거나 바꾸는 변이를 넣어, 그 규칙을 지키는 테스트가 실패하는지 본다. 결함 수정안을 넣었을 때
기존 테스트가 모두 통과하면 그 테스트는 결함을 막지 못했던 것이다(부록 P-13).
- 커버리지 100%인 곳에서도 판정 경계의 변이가 살아남았다(1103 README 5절 원인 5). 커버리지는 줄을 지나갔다는 뜻일
뿐이다.
- 변이 실험은 일괄 실행 목록으로 낸다. 리뷰어가 손으로 만들어 checkout 전체를 잠그며 돌리지 않는다(1105/10-03,
09장 4절).
### 3.3 템플릿 원래 상태 밖에서도 돈다
수정을 템플릿 원래 상태나 작은 입력으로만 확인하면 다운스트림에서 다시 결함이 된다. 4라운드 반복 원인 1번이다
(1105 README 6절, 부록 P-02).
| 확인할 상태 | 지난 예 |
| --- | --- |
| 기능을 하나 이상 더한 상태(`create:feature`) | 기능을 더하면 시각 테스트가 실패했다(1103/12-01) |
| 제품 확장 지점을 채운 상태 | 타입 검사 탐침이 제품 파일을 통째로 덮어써 제품 capability가 있는 복사본에서 FE-GATE-005가 항상 실패(1105/09-01) |
| 예제 기능을 지운 상태 | CHANGELOG 안내대로 예제를 지우면 문서 검사가 실패(1105/14-01) |
| 입력·객체가 셋 이상 | purge 수정 테스트가 객체 0~1개만 써서 3개 이상의 결함을 놓쳤다(1103/05-01 남은 부분) |
| 매뉴얼 예시 이름으로 만든 기능 | 템플릿 테스트의 글자가 제품 기능 이름과 부딪쳐 제거 드릴 실패(1105/16-04) |
### 3.4 단언이 대상에 닿는가
- fixture가 비어 첫 줄에서 return하지 않는가. 전제(예: 포커스가 먼저 옮겨졌는가)를 함께 단언하는가.
- 실제 화면이 아니라 로딩 화면·오류 화면·fixture 자신을 검사하지 않는가. 접근성 e2e가 기능의 빈 목록이 아니라 오류
화면을 검사하고 "passed"로 적은 적이 있다(1103/11-01). 부록 P-15.
## 4. 환경에 기대지 않는다
| 기대는 것 | 증상 | 기준 |
| --- | --- | --- |
| gitignore된 로컬 생성물 | 깨끗한 clone에서 실패 | 테스트가 필요한 생성물을 스스로 만든다. 한 파일 실행도 `scripts/run-vitest.ts`를 거친다(07장 1절) |
| 작성자 PC의 글꼴·CPU | 다른 호스트에서 시각·규모 테스트 실패 | 글꼴은 `fonts.conf`로 고정한다(1101 README 343줄). 규모 테스트는 CPU와 무관한 비교만 단언한다 |
| 바깥 env(빌드 식별값, `CI=true`) | 실제 CI에서만 실패 | 테스트가 띄우는 빌드·dev server의 env는 테스트가 정한다(1103/11-06·11-07·11-08, 07장 4절) |
| 고정 출력 경로·고정 포트 | 한 checkout에서 두 실행이 부딪힌다 | 실행별 출력 폴더와 빈 포트 [제안]. 실행 격리 방법은 결정 대기다(08장 5.1절 D6, 1105/12-04) |
| 호스트 권한(user namespace 등) | 사전 점검 PASS 뒤 원문 오류 | 사전 점검이 본 단계와 같은 방법으로 한 번 실행해 본다(07장 5절) |
| 옆 checkout(짝 백엔드) | 기계마다 결과가 다르다 | 없으면 "확인 못 함"으로 보고한다(07장 6절, 1105/12-02) |
## 5. 가끔 떨어지는 테스트
### 5.1 금지
- 재시도, timeout 늘리기, worker 줄이기, `force` 클릭·합성 이벤트로 덮지 않는다(전략 16.5절, 19절. 1103/11-10 조사에서
버린 대안).
- skip은 Playwright spec에만, owner·defect·route·만료일이 있는 quarantine으로만 둔다(`scripts/check-test-evidence.ts`).
빠른 계층에는 quarantine이 없다. 고치거나 느린 층으로 옮긴다(1101 README 441줄, 2026-11-03 결정).
- "부하 탓"으로 닫지 않는다. 부하를 낮춘 재현과 결정적 재현으로 확인하기 전에는 원인이 아니다. 1103 조치에서 부하
탓으로 적었던 두 실패는 모두 테스트 결함이었다(1103 README 14.7절 정정 두 줄).
### 5.2 조사 절차
1. **반복 실행으로 빈도를 잰다.** 같은 조건에서 30회 같은 식으로 돌려 실패 수를 적는다(1103/11-10: 30회 두 번, 각각
60건 중 3건 실패).
2. **실패 기록을 남긴다.** 이벤트 순서(pointerdown·pointerup·click 대상), 위치, 시각, 네트워크 로그를 실패한 실행에서
모은다. 진단용 코드는 별도 브랜치에 둔다.
3. **결정적 재현을 만든다.** 원인이라고 본 조건을 강제로 만들어 매번 실패하게 한다. 예: mousedown 때 앱 높이를 늘리면
세 엔진 6/6 실패(1103/11-10). 모듈 응답을 3.5초 늦추면 WebKit 경고 2/2(1103/11-09).
4. **고친다.** 고친 뒤 결정적 재현이 통과하고, 실제 조건 반복 실행에서 실패 0인지 본다(1103/11-10: 660/660).
5. **검사가 약해지지 않았는지 변이로 본다.** 경고를 무시하게 고쳤으면, 원래 잡아야 할 것(예: 정말 안 쓴 preload)을
여전히 잡는지 변이로 확인한다(1103/11-09 수정, 1105 README 3.3절).
### 5.3 브라우저 테스트에서 반복된 원인
| 원인 | 예 | 기준 |
| --- | --- | --- |
| 브라우저의 추정에 기댄다 | WebKit이 load 3초 뒤 한 번 하는 "preload를 안 썼다" 추정. 곧 쓰일 preload로 가끔 실패하고, 정말 안 쓴 preload는 놓쳤다(1103/11-09) | 브라우저 경고 대신 확인하려는 사실(preload가 평가됐는가)을 직접 검사한다. 부록 P-17 |
| 그리는 중인 화면을 누른다 | 앱 뒤에 붙인 버튼이 렌더링 중 12 px 밀려 클릭이 버튼에 닿지 않았다(1103/11-10) | 테스트가 붙이는 조작 요소는 앱 레이아웃과 무관한 고정 층에 둔다. "다 그려질 때까지 기다리기"는 신호가 없어 쓰지 않는다. 부록 P-18 |
| 짧은 상태를 폴링으로 잡는다 | 500 ms만 이어지는 `BLOCKED` 상태를 폴링으로 잡으려다 두 엔진에서 실패(1103/11-05) | 상태 변화를 이벤트·기록으로 받는다 |
| 고정 상한과 첫 실행 비용 | provider 테스트 10개가 10초 상한에 묶이고, 하나만 고르면 첫 테스트가 fixture 빌드를 떠안아 실패(1103/11-03) | 무거운 준비는 suite 준비 단계로 옮기고 suite가 자기 timeout을 선언한다 |
## 6. 테스트 실행 비용
- 빠른 계층(`tests/unit`)에 프로세스를 띄우는 도구 테스트, 실제 시계로 기다리는 테스트가 섞이면 전체가 느려진다
(1101/10-05~10-07, 부록 P-21).
- merge 단계가 같은 파일을 두 번 돌리지 않는지 본다(1101/10-06).
- 긴 드릴은 시간을 함께 적는다. FE-GATE-020은 1,150초 안팎, `test:feature-scaffold`만 513~866초다(1103 README 14.7절,
1105 README 11.1절). 45분 job 상한과의 여유를 본다.
## 지금 이해하면 되는 것
- 테스트 위치는 필요한 실행 환경으로 정한다(`taxonomy.md`).
- 검출력은 변이로, 범위는 템플릿 원래 상태 밖(기능 추가·예제 제거·입력 셋 이상)으로 확인한다.
- 가끔 떨어지는 테스트는 재시도·timeout으로 덮지 않는다. 반복 실행 → 실패 기록 → 결정적 재현 → 수정 → 변이 순서로
원인을 찾는다.
+96
View File
@@ -0,0 +1,96 @@
# 06. 성능·최적화 기준
## 핵심
이 템플릿의 성능 목표는 **예산**이다. 요청량·데이터량 목표는 없다(1105 README 0절). 예산은 세 측정 맥락으로 나뉘고,
맥락마다 재는 곳과 막는 게이트가 다르다.
```text
번들(빌드 산출물) ── check:bundle FE-GATE-012 merge 단계 초기 JS bytes·파일 수, lazy 청크 bytes
lab(실험실 브라우저) ── test:performance FE-GATE-026 release 단계 LCP·CLS·이름 붙은 상호작용(중앙값)
field(운영 표본) ── field Web Vitals FE-GATE-018 field 단계 p75 LCP·CLS·INP, 28일
```
숫자의 정본은 `config/performance/budgets.json`이고, 세 맥락의 계약은 `docs/operations/performance-evidence.md`
1~13줄이다. 이 장은 숫자를 다시 적지 않는다. **언제 재는지, 어떤 조건으로 재는지, 숫자를 고칠 때 무엇을 같이
하는지**만 정한다.
## 1. 정본
| 무엇 | 정본 |
| --- | --- |
| 예산 값 | `config/performance/budgets.json` |
| 세 맥락의 계약과 측정 항목 | `docs/operations/performance-evidence.md` |
| 번들 예산 검사 | `scripts/check-bundle.ts`(`check:bundle`) |
| lab 측정 | `scripts/test-performance.ts`(`test:performance`), 기본값 `scripts/lib/lab-performance.ts`(5회, 포트 4173) |
| 템플릿 그대로의 초기 JS 기준선, 기능·context 하나당 증가량, 그 기록을 재는 테스트와 갱신 명령 | `docs/operations/performance-evidence.md` 「번들 예산의 기준선과 여유」 절. 기록 파일과 측정 스크립트는 참조 기능과 함께 지워지므로 이 매뉴얼은 이름을 쓰지 않고 그 절을 가리킨다(07장 6절) |
| 규모 설계와 예산의 근거 | `docs/architecture/scale-architecture.md` |
| 측정 결과에 붙일 정보의 일반론 | 가이드 14절 「측정 결과에 반드시 붙일 정보」 |
## 2. 언제 재나
| 바꾼 것 | 잴 것 |
| --- | --- |
| 라우트 로딩, dynamic import, 초기 화면, 청크 나누기(`vite.config.ts`) | `check:bundle`과 `test:performance` 둘 다 |
| 의존성 추가·갱신 | `check:bundle`. 갱신 하나가 초기 JS를 약 7 KB 늘려 예산을 넘긴 예가 있다(1103/13-03, zod 4.6.x) |
| 기능 추가(`create:feature`) | 생성 명령의 `Next:` 안내대로 초기 JS 기록을 다시 쓰고 FE-GATE-005·012를 돌린다(1103 README 14.6절 #2) |
| 성능 최적화 작업 | 바꾸기 전·후를 같은 조건으로(3절) |
lab 게이트는 release 단계에만 있다. merge 게이트만 돌리면 lab 회귀를 모른다. 예제 화면 진입 회귀가 147커밋 동안 아무
게이트에도 걸리지 않았다(1103/15-01). 라우트 로딩을 건드린 커밋은 merge 게이트에 더해 `test:performance`를 돌린다
(07장 2절).
## 3. 측정 조건
측정값에는 아래를 함께 적는다. 하나라도 빠지면 다른 측정과 비교하지 않는다(가이드 14절).
| 항목 | 이 repo에서 |
| --- | --- |
| 위치 | desktop(07장 7절). 노트북 측정은 비교에 쓰지 않는다 |
| 하드웨어·런타임 | CPU 모델·논리 코어 수·Node 버전. lab 결과 JSON이 자동으로 담는다 |
| 부하 | 측정 앞뒤의 load average. lab 결과 JSON이 담는다. 다른 무거운 실행과 겹치지 않게 잠금 아래에서 잰다 |
| 브라우저와 조건 | lab: Chromium, 1280×720, `contract-fast-4g`, CPU 4배 감속, 빈 캐시·새 browser context(`scripts/test-performance.ts` 211~221줄) |
| 반복과 통계 | 기본 5회의 중앙값으로 판정한다. 표본 전부와 퍼짐을 함께 적는다(같은 파일 226~231줄). 예: "중앙값 227 ms(표본 223·224·227·438·526)"(1103/15-01) |
| 빌드 | 커밋과 build id. 비교하는 두 빌드는 같은 env로 만든다. 커밋 ID가 빌드에 박혀 초기 JS가 몇 바이트 달라진다(1103 README 14.5절 10회차) |
| 대조군 | 바꾸기 전 커밋을 같은 세션·같은 조건에서 함께 잰다. 지난 측정값을 대조군으로 쓰지 않는다 |
| 규모 | 기능 수에 따른 비용은 참조 기능을 복제한 실제 모양 기능 25개·100개로 재고 호스트 부하를 함께 적는다(`SPEC.md` D-18) |
## 4. 예산 사이의 균형
- **초기 JS bytes와 초기 파일 수는 함께 본다.** bytes를 줄이려고 청크를 나누면 파일 수가 는다. HTTP/1.1에서는 요청이
줄을 서서 첫 화면이 늦어진다. 파일 수 상한은 HTTP/2 호스팅을 전제로 정했다(`docs/operations/performance-evidence.md`
「초기 청크 수와 HTTP/1.1」, 1103 README 14.6절 #4).
- **청크 이름으로 크기를 판단하지 않는다.** 공용 청크는 안에 든 모듈 하나의 이름을 받는다. 출처별 크기는
sourcemap으로 나눠 잰다(같은 문서 「번들 예산의 기준선과 여유」).
- **재방문 비용도 본다.** release마다 이름이 바뀌는 청크에 큰 라이브러리가 들어가면 코드가 같아도 다시 받는다(같은 문서
「build id와 재방문 캐시」).
- **여유를 적는다.** 예산에서 기준선을 뺀 여유와, 기능 하나가 쓰는 양을 함께 보고한다. 1103 조치 끝에 초기 JS 여유가
쓰기 기능 하나 남짓이었다(1103 README 14.5절 끝 문단, 14.7절).
## 5. 숫자를 고칠 때
- **기준선 기록**은 손으로 고치지 않는다. 측정 스크립트를 `--initial-baseline --write`로 돌리고 같은 변경에 넣는다
(`docs/operations/performance-evidence.md` 35~36줄). 손으로 적은 숫자는 두 번 낡았다(같은 문서 22줄).
- **대조 허용치는 남은 여유보다 작아야 한다.** 기록 대조 허용 1%(약 2 KB)가 남은 여유(1,873 B)보다 커서 여유를 다 쓰는
변경이 통과할 수 있다(1105/15-02). 허용치를 정할 때 여유·측정 오차와 비교한다. 부록 P-46.
- **예산 값**(`config/performance/budgets.json`)을 올리는 것은 결정이다. 이유·대안·재검토 조건을 08장 형식으로 남긴다.
예: 초기 파일 수 상한을 26에서 32로 올린 것(1103 README 14.6절 #4).
- **문서에 측정값을 적을 때**는 커밋과 측정일을 붙인다. 그 숫자가 지금 빌드와 다를 수 있다고 적는다.
## 6. 성능 쪽 반복 결함
| 패턴 | 막는 기준 |
| --- | --- |
| release 단계에만 있는 게이트의 회귀를 아무도 모른다(1101/15-01, 1103/15-01) | 2절: 라우트 로딩을 건드리면 `test:performance`도 돌린다 |
| 실패 메시지가 무엇을 얼마나 넘었는지 말하지 않는다(1103/15-03) | 예산 검사는 넘은 항목·잰 값·초과량을 모두 출력한다(`docs/operations/performance-evidence.md` 5~7줄) |
| 측정 조건 없이 숫자만 남아 비교할 수 없다 | 3절 표 |
| lab이 화면 하나·조건 하나만 잰다. 기능 라우트 첫 진입(약 400 ms), `/` 밖 화면의 layout shift, 스크롤바가 보이는 환경을 어느 게이트도 재지 않는다(1105/15-04, 15-01, 15-05, 모두 미조치) | 기능 라우트 로딩을 바꾸면 그 라우트 첫 진입을 lab과 같은 조건으로 따로 재고 결과에 적는다 **[제안]** |
| 부하가 높은 시간대의 실패를 "부하 탓"으로 닫는다. 두 번 다 원인은 테스트에 있었다(1103/11-09, 11-10) | 05장 5절: 부하를 낮춘 재현과 결정적 재현으로 확인한 뒤에만 부하를 원인으로 쓴다 |
전체 목록은 부록의 「성능」 행이다.
## 지금 이해하면 되는 것
- 예산 숫자는 `config/performance/budgets.json`, 맥락별 계약은 `performance-evidence.md`가 정본이다.
- 라우트 로딩을 건드리면 merge 게이트에 더해 lab 게이트도 돌린다.
- 측정값에는 위치·부하·반복 수·빌드·대조군을 붙인다. 붙이지 않은 숫자는 비교하지 않는다.
+177
View File
@@ -0,0 +1,177 @@
# 07. 검증과 게이트
## 핵심
무엇을 돌릴지는 **언제인지**로 정한다. 작업 중에는 바뀐 테스트 파일만, 커밋 전에는 빠른 게이트 8개, 통합 때는
5개를 더, merge 가능을 말할 때는 merge 단계 14개를 CI와 같은 env로 돌린다.
```text
작업 중 바뀐 테스트 파일 하나 (1절)
커밋 전 빠른 게이트 8개 (2절, SPEC.md 31줄)
레인 끝·통합 + 5개 (2절, SPEC.md 32줄)
merge 판정 ci:gate로 merge 단계 14개, workflow env (3절)
리뷰 시작 merge 단계 14개 + verify:documentation (3절, CLAUDE.md 리뷰 절차 2단계)
```
게이트 ID·단계·명령의 정본은 `config/ci/gates.json`이다. 이 장은 그 목록을 다시 적지 않는다.
## 1. 명령 규칙
- 패키지 스크립트는 `corepack pnpm <script>`로 돌린다. `npm run`으로 돌리면 제거 드릴이 `npm_execpath`를 pnpm으로
가정해 모든 검사가 `Unknown command`로 실패한다(1103 README 10.4절).
- 테스트 파일 하나는 `node scripts/run-vitest.ts run <file>`로 돌린다. 이 runner가 `src/.generated/`를 먼저 만든다.
`pnpm exec vitest run <file>`은 그 단계를 건너뛰어 import 오류로 실패하고, `pnpm test:unit -- <file>`은 범위를
좁히지 않는다(`docs/testing/taxonomy.md` 42~53줄).
- 실패를 경고로 낮추지 않는다. `continue-on-error`나 경고만 내는 스크립트를 쓰지 않는다(`docs/testing/taxonomy.md`
3~4줄).
## 2. 언제 무엇을
| 때 | 돌릴 것 | 근거 |
| --- | --- | --- |
| 작업 중 | 바뀐 테스트 파일. 브라우저 테스트는 그 spec 하나 | 1절 |
| 커밋 전(작업마다) | `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema` | `SPEC.md` 31줄 |
| 레인 끝·통합 | 위에 더해 `check:ci`, `check:adapter-inventory`, `verify:documentation`, `test:sample-removal`, `build` | `SPEC.md` 32줄 |
| 브랜치를 합칠 때마다 | 커밋 전 8개. 합친 뒤에만 생긴 실패는 기록한다 | 1103 README 14.1·14.3절 |
| merge 가능이라고 말하기 전 | merge 단계 14개(3절) | 사용자 지시 |
| 리뷰 시작 | merge 단계 14개(3절)와 `verify:documentation`(FE-GATE-017) | `CLAUDE.md` 27줄. 손으로 적은 명령 목록만 돌리다 merge 게이트 둘을 놓친 일(1103 README 10.5절)로 목록을 merge 단계로 바꿨다(1105/12-03) |
| 라우트 로딩·청크·초기 화면을 바꿀 때 | merge 단계에 더해 `check:bundle`(FE-GATE-012)과 lab 게이트 `test:performance`(FE-GATE-026) | 06장 2절 |
| 공급망·release 경로를 바꿀 때 | release 단계 게이트(`config/ci/gates.json`의 `stages` 중 `release`) | 4절 |
release 단계 게이트는 merge 단계에 없다. 그래서 lab 게이트 회귀가 147커밋 동안 아무 게이트에도 걸리지 않았다
(1103/15-01, 1103 README 5절 원인 2). 바꾼 것이 release 단계 게이트가 지키는 것에 닿으면 그 게이트도 돌린다.
## 3. merge 가능 판정
"merge 가능"은 다음 방법으로만 말한다(사용자 지시). 고른 스크립트 목록이 다 통과했다는 것은 merge 가능의 근거가
아니다. 스크립트를 골라 "23개 통과"라고 보고했지만 merge 게이트 셋이 실패하던 적이 있다(2026-11-03).
1. **대상:** `config/ci/gates.json`의 `stages` 중 `merge`의 `gateIds` 14개(FE-GATE-001~013, FE-GATE-020).
2. **명령:** 게이트마다 `corepack pnpm ci:gate -- FE-GATE-0NN`. workflow도 같은 명령을 쓴다
(`.gitea/workflows/quality-gates.yml` 74줄).
3. **env:** workflow의 전역 env(`.gitea/workflows/quality-gates.yml` 25~31줄)를 그대로 준다.
| 변수 | 값 |
| --- | --- |
| `CI` | `true`. 빼지 않는다. 이 값이 있어야 빌드 식별값을 엄격하게 검사한다 |
| `VITE_COMMIT_SHA` | 40자리 커밋 SHA |
| `VITE_BUILD_ID` | `gitea-<run>-<attempt>` 꼴 |
| `RELEASE_ID` | `<ref>-<run>-<attempt>` 꼴 |
| `CI_RUNNER_IMAGE` | `<image>@sha256:<64자리>` 꼴 digest |
`CI=true` 없이 "14개 통과"라고 했다가, 넣자 FE-GATE-005·008·020이 실패한 적이 있다(1103 README 14.5절 끝 문단,
1103/11-08).
4. **작업 폴더:** 깨끗한 checkout. 노트북 main checkout은 `.claude/worktrees/`를 품고 있어 `test:system`의 repo 복사와
vite 파일 감시가 깨진다. desktop checkout에는 이 폴더가 없다(7절).
5. **한 게이트 안의 명령:** `ci:gate`는 그 게이트의 명령 중 첫 실패에서 멈춘다. 뒤 명령의 결과가 필요하면 따로 돌린다.
4라운드는 FE-GATE-013의 `test:system` 뒤 명령 7개를 따로 돌렸다(1105 README 11.1절).
6. **기록:** 게이트마다 결과·시간·핵심 숫자(테스트 수, 초기 JS 바이트, 파일 수)와 실행 시점의 부하를 표로 남긴다.
게이트 로그는 `artifacts/quality/gates/FE-GATE-0NN.txt`에 쌓인다. 실패를 고칠 때마다 다시 돌리고 회차를 남긴다
(1103 README 14.5절 표).
### 3.1 가끔 떨어지는 게이트
- **다시 돌려 통과시킨 결과를 "통과"로 쓰지 않는다.** 실패한 회차를 그대로 적고 원인을 찾는다(05장 5절).
1103 조치에서 FE-GATE-008이 "세 번째 실행에서 통과"로 적혔던 두 실패는 둘 다 테스트 결함이었다(1103/11-09,
1103/11-10).
- 원인을 고친 뒤에는 같은 게이트를 연속으로 여러 번 돌려 실패 0을 적는다. FE-GATE-008은 연속 3회였다(1103 README
14.5절 12~14회차).
### 3.2 desktop에서 FE-GATE-013
desktop에서는 FE-GATE-013의 `test:system` 중 provider 테스트 18건이 호스트 원인으로 실패한다. ssh 셸에서 비특권
user namespace가 막혀 `bwrap --unshare-net`이 실패한다. 사전 점검은 이 조건을 보지 않고 PASS를 낸다(1105/12-01).
- 러너 전제를 어떻게 할지는 **결정 대기**다(1105 README 7절 D4). 결정 전까지 merge 판정 보고에는 FE-GATE-013을
"환경 실패"로 적고, 실패 18건이 모두 그 원인인지와 뒤 명령 7개의 결과를 함께 적는다(1105 README 11.1절 표).
- 시스템 설정은 바꾸지 않는다.
## 4. CI env에서만 나는 실패
로컬 env로 통과해도 workflow env에서 실패하는 결함이 반복됐다(부록 P-05).
| 발견 | 모양 |
| --- | --- |
| 1103/11-06 | e2e가 build id를 `"local-build"`로 고정했다. workflow는 `VITE_BUILD_ID`를 넣으므로 FE-GATE-008이 실제 CI에서 항상 실패 |
| 1103/11-07 | workflow 전역 env의 빌드 식별값이 vitest와 dev server로 새어, merge 게이트 다섯 개가 실제 CI에서 항상 실패 |
| 1103/11-08 | `CI=true`가 테스트 안의 로컬 빌드까지 release 빌드로 검사되게 해, merge 게이트 셋이 workflow env에서 실패 |
기준:
- merge 판정은 3절 env로만 한다.
- 테스트는 바깥 env에서 무엇을 물려받는지 고정한다. 테스트가 직접 띄우는 빌드·서버의 env는 테스트가 정한다
(04장 6절).
## 5. 검사가 PASS인데 그 뒤가 실패
사전 점검·준비 단계가 "통과"를 내고, 그 뒤 실제 단계가 원인 없는 원문 오류로 실패하는 결함이다(부록 P-07).
- 1105/12-01: `scripts/check-system-test-prerequisites.ts`가 실행 파일·cgroup·systemd bus만 보고 bwrap을 실제로
돌리지 않는다. 그래서 PASS 뒤 provider 테스트가 bwrap 원문 오류로 떨어진다.
- 1103/11-04: `test:system`이 git worktree에서 `.git` 때문에 실패하는데 사전 점검은 PASS를 낸다.
기준: 사전 점검은 **본 단계가 쓰는 것과 같은 방법으로** 한 번 실행해 본다. 실패하면 원인 이름을 붙여 멈춘다.
존재 여부만 보는 점검은 PASS가 아니라 "확인 안 함"으로 적는다(`SPEC.md` 「결정」 D-14의 `UNVERIFIED` 원칙).
## 6. 문서 검사
`verify:documentation`(FE-GATE-017, documentation 단계)이 문서를 검사하는 범위와 방법의 정본은
`scripts/verify-documentation-readiness.ts`와 `docs/README.md` §1 끝 문단이다.
- **범위:** `docs/README.md`와, 그 §1이 링크한 문서. 폴더 링크는 그 폴더 바로 아래 `.md`만 본다. 이 매뉴얼은 §1에서
링크되어 범위 안이다(README 결정 M-3).
- **보는 것:** 백틱 안의 repo 경로(`:줄` 꼬리는 떼고 본다), 셸 코드 블록과 백틱 안 명령의 경로 인자, 마크다운 링크,
`corepack pnpm <script>`와 백틱 안 `<prefix>:<name>` 꼴의 package script, `FE-GATE-0NN` ID가 실제로 있는가.
- **보지 않는 것:** 설명·수치가 코드와 맞는가.
- **예외:** git이 무시하는 생성 산출물, 복사한 프로젝트가 지운 작업 이력(루트 `README.md` 「Files you can delete after
copying」의 경로)은 없어도 된다.
- **짝 백엔드 경로:** `clean-architecture-backend-template/<경로>` 꼴의 경로와 그 repo로 나가는 링크는 옆 checkout이
있을 때만 확인한다. 없으면 실패가 아니라 "확인 못 함"으로 남긴다. 옆 checkout이 다른 커밋이면 실패한다. desktop의 옆
백엔드 checkout은 pin과 다른 커밋이라, desktop에서는 백엔드 참조 몇 곳 때문에 실패할 수 있다(1105 README 11.1절,
1105/12-02). 그때는 실패가 그 참조뿐인지 확인해 적는다.
- **도는 곳:** FE-GATE-017은 documentation 단계라 merge 체인 밖이다. 그러나 같은 검사가 merge 게이트 안에서도 돈다.
`tests/unit/documentation-readiness.test.ts`가 문서를 복사해 검사를 돌리고(FE-GATE-005), 기능을 지우거나 더한 사본을
만드는 FE-GATE-020의 두 드릴(`test:sample-removal`, `test:feature-scaffold`)도 문서를 복사해 돌린다
(`scripts/lib/removal-fixture.ts` 50~60줄). 그래서 §1 문서의 경로 하나가 틀리면 merge가 막힌다.
- **샘플과 함께 지워지는 경로는 새 문서에서 이름으로 쓰지 않는다.** 참조 기능 폴더, 그 기능의 테스트, 기능 모양
기준선 파일과 측정 스크립트 같은 것이다(목록: `scripts/test-sample-removal.ts`의 머리말과 `SAMPLE_EXTRAS`). 백틱으로
쓰면 샘플 제거 사본에서 "없는 경로"가 되어 FE-GATE-020이 실패한다. 백틱을 빼면 그 경로가 검사 밖으로 나간다. 1103
조치가 참조 기능 경로 26줄을 백틱 밖으로 옮긴 것이 검사 약화로 기록됐다(1105/14-03, Low·P3, 미조치). 그래서 그
경로를 소유한 문서의 절을 가리킨다(예: 06장 1절).
- **돌리는 법:** `corepack pnpm verify:documentation`. 옆 checkout 없는 임시 worktree에서 `pnpm`으로 돌리면 pnpm이
`node_modules` 재설치를 시도하다 멈춘다. 그런 곳에서는 `node scripts/verify-documentation-readiness.ts`로 직접
돌린다(1105 README 11.5절).
- 문서 관련 unit 테스트: `tests/unit/documentation-readiness.test.ts`, `tests/unit/deletable-history-documents.test.ts`,
`tests/unit/changelog-review-ids.test.ts`.
## 7. 소유자 환경
이 절은 이 repo 소유자의 기계에 묶인 규칙이다. 복사한 프로젝트는 이 절을 자기 환경으로 바꾼다(README 결정 M-4).
출처: 2026-11-05 사용자 지시와 그날의 실행 기록(1105 README 11절).
- **테스트·게이트는 노트북에서 돌리지 않는다.** 노트북은 다른 작업과 함께 돌아 전체 테스트에 죽는다. `ssh desktop`의
/home/donghyeon/workspace/clean-architecture-frontend-template 에서 돌린다.
- **변경은 git으로 보낸다.** push하지 않은 브랜치는 노트북에서 직접 보낸다. remote는 더하지 않는다.
```bash
git push desktop:/home/donghyeon/workspace/clean-architecture-frontend-template <branch>:refs/heads/<branch>
```
보내기 전에 desktop에서 `git status`가 비었는지 본다. 바뀐 파일이 있으면 덮어쓰지 말고 먼저 확인한다.
- **PATH.** 비대화형 ssh에는 node가 없다. `export PATH=$HOME/.nvm/versions/node/v24.14.0/bin:$PATH`를 먼저 한다.
- **잠금.** 무거운 실행은 `flock /tmp/claude-gates/heavy.lock`으로 감싸 하나씩 돌린다. 백엔드 세션도 같은 desktop에서
같은 잠금을 쓴다.
- **merge 단계 runner.** desktop의 /tmp/claude-gates/run-merge-stage.sh 가 3절의 env를 넣고 게이트마다 잠금 아래
`ci:gate`를 돌려 `summary.txt`와 게이트별 로그를 남긴다. `GATES="005 008"`처럼 일부만 돌릴 수 있다. 오래 걸리므로
`nohup setsid`로 띄우고 끝나기를 기다린다.
- **끝나면 되돌린다.** 다른 세션도 같은 checkout을 쓴다. 실행이 끝나면 checkout을 처음 브랜치로 되돌리고
`git status`가 비었는지 본다.
- **노트북에서 꼭 돌려야 하면** main checkout이 아니라 깨끗한 복제본(`git clone --no-hardlinks`, 그 뒤
`corepack pnpm install --frozen-lockfile --offline`)에서 돌린다. 노트북은 inotify 감시가 부족해 vite가 들어가는
게이트에 `CHOKIDAR_USEPOLLING=1`을 준다. 시스템 한도는 바꾸지 않는다.
## 지금 이해하면 되는 것
- 커밋 전 8개, 통합 때 5개 더, merge 판정은 `ci:gate`로 14개를 workflow env(`CI=true` 포함)로.
- 다시 돌려 통과한 것은 통과가 아니다. 원인을 찾고, 고친 뒤 연속 실행으로 확인한다.
- 실행은 desktop에서, 잠금 아래에서, 끝나면 checkout을 되돌린다.
+127
View File
@@ -0,0 +1,127 @@
# 08. 결정과 기록
## 핵심
결정은 **한 번 하고, 한 곳에 적고, 다시 묻지 않는다.** 이 repo의 결정은 리뷰 README·`SPEC.md`·ADR에 흩어져 있다.
이 장은 그 결정들의 **색인**이다. 원문은 옮기지 않고 출처만 단다(README 결정 M-6).
```text
리뷰가 선택지를 낸다 → 리뷰 README 「결정이 필요한 것」
소유자가 고른다 → 같은 README 「조치」의 결정 표 (또는 SPEC.md 「결정」, ADR)
이 장의 색인에 한 줄 → 다음 작업은 여기부터 찾는다
```
## 1. 결정을 적는 곳
| 결정의 종류 | 적는 곳 | 형식 |
| --- | --- | --- |
| 리뷰 중 나온 선택 | 리뷰 README 「결정이 필요한 것」 | 번호·결정·선택지·관련 발견·결정할 사람(1103 README 6절, 1105 README 7절) |
| 그 선택을 고른 것 | 같은 README 「조치」 절의 결정 표 | 번호·고른 것·이유(1103 README 14.2절). 버린 대안이 있으면 함께(1101 README 14.1절) |
| 수정 라운드 전체의 기본값 | `SPEC.md` 「결정」 표 | ID·대상·결정(`SPEC.md` 39~63줄) |
| 오래 가는 구조·기술 선택 | `docs/architecture/decisions/VD-*.md` | 상태·결정일·맥락·결정·대안 |
| 규칙의 예외 | 그 규칙의 `comment`(이유·담당·재검토 조건) | `docs/architecture/layers.md` 104~117줄 |
| 다운스트림에 보이는 변경 | `CHANGELOG.md` 미출시 절 | 동기화 단위의 순 변경 요약(1103 README 14.2절 D5) |
| 한 커밋 안의 선택 | 커밋 본문 「고른 방법과 버린 대안」 | 커밋 규칙 3.3절 |
| 이 매뉴얼을 만들며 정한 것 | 이 매뉴얼 README 「결정 기록」 | M-1~ |
## 2. 결정 표에 들어갈 것
- **고른 것과 이유.** 이유는 "더 낫다"가 아니라 무엇을 지키는지로 쓴다.
- **버린 대안과 버린 이유.** 다음 사람이 같은 대안을 다시 꺼내지 않게 한다.
- **확인한 사실 / 기록된 의도 / 추론을 나눈다**(가이드 41.3절). 확인하지 않은 것은 "미확인"이라고 쓴다. 다운스트림
파일을 열지 않고 이름으로 추정한 문장이 CHANGELOG에 틀린 이행 안내로 남은 적이 있다(1103/14-02).
- **재검토 조건.** 어떤 규모·버전·계약 변화가 결론을 바꾸는지.
## 3. 결정을 다시 묻지 않는다
1. 결정이 필요해 보이면 먼저 아래 4절 색인과 가장 최근 리뷰 README의 결정 절을 찾는다.
2. 이미 정했으면 따른다. 상황이 바뀌어 뒤집어야 하면 새 결정으로 적고 옛 결정을 가리킨다. 옛 기록을 고치지 않는다.
3. 정한 적이 없으면 5절 형식으로 결정 대기를 만든다. 스스로 정하지 않는다. 다만 사용자가 위임한 범위 안에서는
총괄이 정하고 그 위임 문장을 출처로 적는다(예: 1101 README 14절 머리말 "결정 대기 부분을 지금 바로 결정하고
처리").
## 4. 결정 색인
「출처」의 리뷰 README는 `docs/reviews/<날짜>-maturity-review/README.md`다. 「repo 밖」은 소유자 지시가 세션 기록과
작업 메모에만 있던 것이다. 이 매뉴얼의 해당 장이 그 규칙의 repo 안 기록이 된다.
### 4.1 작업 방식 (소유자 지시)
| # | 날짜 | 결정 | 출처 | 이 매뉴얼 |
| --- | --- | --- | --- | --- |
| O-1 | 2026-09-16 | 이 repo는 템플릿이다. 소비자 없는 코드와 빈 레지스트리는 확장 지점이지 죽은 코드가 아니다 | `CLAUDE.md` 19줄 | 03장 2절 |
| O-2 | 2026-09-16 | adapter 배럴을 공개 경계로 만든다(배럴 폐지안 기각) | `CLAUDE.md` 20줄, `docs/architecture/layers.md` 119줄 | 03장 2절 |
| O-3 | 2026-09-16 | 갈라진 IndexedDB 복사본은 kernel(`src/adapters/platform/`)로 모은다. 새 파일 단위 예외를 만들지 않는다 | `CLAUDE.md` 21줄, `SPEC.md` 34줄 | 03장 2절 |
| O-4 | 2026-11-01 | 커밋·PR은 커밋 규칙 문서를 따른다. AI 꼬리말(`Co-Authored-By: Claude`, 세션 링크, "Generated with Claude Code")은 어디에도 넣지 않는다 | 커밋 규칙 0·3.4절(repo 밖) | 5절 |
| O-5 | 2026-11-03 | merge 가능 판정은 `ci:gate`로 merge 단계 14개를 workflow env로 돌려서 한다. 고른 스크립트 목록으로 판정하지 않는다 | repo 밖. 실행 기록은 1103 README 14.5절 | 07장 3절 |
| O-6 | 2026-11-03~05 | 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 이유와 함께 남긴다 | repo 밖 | 09장 5.3절 |
| O-7 | 2026-11-03~05 | 리뷰·수정에 스킬을 쓴다 | repo 밖 | 01장 0절 |
| O-8 | 2026-11-03~05 | 총괄 세션은 하위 세션에 일을 맡긴다 | repo 밖 | 09장 1절 |
| O-9 | 2026-11-04 | 수정 → 리뷰를 반복한다. 새 High 0·새 P1 0·merge 게이트 14개 통과면 그 라운드의 Medium·Low를 고치고 멈춘다. 세 라운드를 더 돌아도 닿지 않으면 멈추고 이유를 보고한다 | repo 밖 | 09장 5절 |
| O-10 | 2026-11-05 | 테스트·게이트는 노트북에서 돌리지 않고 desktop checkout에서 돌린다 | repo 밖 | 07장 7절 |
| O-11 | 2026-11-05 | 리뷰 중 실행은 게이트를 한 번 돌리고 산출물을 함께 읽는다. 추가 실험은 목록으로 모아 같은 명령은 한 번만, 실험마다 작업 폴더를 되돌리며 일괄로. 작업 폴더 복제본을 늘려 해결하지 않는다 | 1105 README 11.4절 | 09장 4절 |
| O-12 | 2026-11-05 | 백엔드와 다른 종료 조건을 각자 유지한다(「각자 유지」). 백엔드는 발견 0까지 확인 리뷰를 반복하고, 프론트는 O-9대로 한다. 차이는 마지막 라운드의 Medium·Low 수정이 확인 리뷰를 받는가다 | repo 밖(백엔드 총괄 세션 전달) | 09장 5.2절 |
| O-13 | 상시 | 짝 백엔드 repo는 읽기만 한다. stage·commit·push하지 않는다 | 1103 README 14.2절 D1 「이유」 | 09장 1절 |
| O-14 | 상시 | 리뷰에서는 코드를 고치지 않는다 | `CLAUDE.md` 15줄 | 01장 1절 |
| O-15 | 2026-11-05 | 수정 결과의 「고침」을 그대로 믿지 않는다. 다음 리뷰에서 ID별로 다시 판정한다 | repo 밖(프론트 총괄 세션 전달). 근거 사례는 1105 README 3.1절 | 09장 5.1·5.3절 |
| O-16 | 2026-11-05 | 큰 라운드는 작은 PR로 나눈다(커밋 규칙 5.1절). 소유자가 PR을 직접 merge한다 | repo 밖(프론트 총괄 세션 전달) | 09장 6절, 이 장 6절 |
### 4.2 기술 결정 (리뷰 라운드)
| 묶음 | 날짜 | 무엇을 정했나 | 출처 |
| --- | --- | --- | --- |
| 0925 수정 라운드 기본값 D-1~D-19 | 2026-09-25 | 결과 불명 intent 보관과 같은 키 재전송(D-1), 효과 분류 선택 필드(D-2), Web Lock 직렬화(D-3·D-4), 확인 못 한 판정은 `UNVERIFIED`(D-14), 문서 색인(D-16), 규모 측정은 실제 모양 기능 25·100개(D-18) 등 | `SPEC.md` 45~63줄 |
| 0929 결정이 필요한 것 7건 | 2026-09-29 | 확장 지점 범위, 409 분류, `x-correlation-id`, fanout 검사, remediation 원장, cross-context kernel 예외, 리뷰 게이트 목록에 `test:system`. 그 라운드에서는 정하지 않았다 | 0929 README 111~121줄 |
| 1101 결정 표 | 2026-11-03 | 확장 지점을 템플릿이 연다, design-system side effect 없음, raw mutation 입력을 공개 훅에서 뺌(BREAKING), 빠른 계층 quarantine 없음 유지(10-04), OPFS 여러 페이지 purge 등 24행 | 1101 README 414~445줄 |
| V2 HTTP 경로 삭제 | 2026-11-03 | HTTP 실행은 V3 하나. 지운 V2 동작의 판정 | 1101 README 602~627줄, 1103 README 3절 |
| 1103 결정 D1~D6 | 2026-11-04 | 짝 업로드는 Fileserver multipart client(D1), 업무 거절은 operation 단위 `refusedBeforeWrite` code 목록(D2), 시각 테스트는 기능 영역을 가리고 찍음(D3), 접근성 e2e 응답 모양(D4), CHANGELOG는 순 변경 요약(D5), 짝 계약은 pin 파일 + 답 표 대조 + drift 검사(D6) | 1103 README 507~516줄 |
| WebKit preload 경고(1103/11-09) | 2026-11-05 | 경고 문구 하나만 무시하고 preload 사용을 세 엔진에서 직접 검사한다(선택지 C) | 커밋 `aad005cb`, 1103 README 14.7절 |
| 구조·기술 ADR | 2026-07-26~28 | `VD-01`~`VD-30`(빈 번호 있음) | `docs/architecture/decisions/` |
## 5. 결정 대기 쓰는 법
못 고치는 발견은 이 형식으로 남긴다. 이 형식을 채우지 못하면 결정 대기가 아니라 미완이다.
| 칸 | 내용 |
| --- | --- |
| 번호·관련 발견 | 예: D4, 1105/12-01 |
| 왜 고치지 못하나 | 예: 러너 전제를 바꾸는 일이라 소유자 결정이 필요하다 |
| 선택지 | 권하는 안을 먼저. 각 안의 비용과 위험 |
| 결정할 사람 | 프론트 소유자 / 두 repo 소유자 / 백엔드 소유자 + reviewer 등 |
| 결정 전까지 | 임시 처리와 보고 방법(예: 07장 3.2절의 FE-GATE-013 기록 방법) |
### 5.1 지금 열린 결정 대기
4라운드 리뷰(1105) 시점이다. 다음 라운드가 닫거나 새로 열면 이 표를 고친다.
| 번호 | 결정 | 관련 | 결정할 사람 | 출처 |
| --- | --- | --- | --- | --- |
| D1 | 운영 advisory 2건(zod·react-router). zod 갱신은 초기 JS 예산을 넘긴다 | 1103/13-03, 1105/13-01 | 프론트 소유자 + reviewer | 1103 README 14.7절, 1105 README 7절 |
| D2 | 플랫폼 구성 화면을 진단 화면으로 인정할지, 기능으로 옮기고 다시 잴지 | 1103/09-04 | 프론트 소유자 | 같음 |
| D3 | 백엔드 생성기의 목록 GET | 1103/03-07 | 두 repo 소유자 | 같음 |
| D4 | FE-GATE-013의 러너 전제(비특권 user namespace) | 1105/12-01 | 프론트 소유자 | 1105 README 7절 |
| D5 | 제품 merge 검사와 release의 관계 | 1105/13-02 | 프론트 소유자 | 같음 |
| D6 | 실행 격리: 실행별 출력·빈 포트, 또는 "한 checkout 한 실행" 명시 | 1105/12-04 | 프론트 소유자 | 같음 |
## 6. 커밋·PR
정본은 repo 밖 `design-docs/conventions/commit-and-pr.md`다. 이 repo에서 덧붙이는 것만 적는다.
- **제목:** `type(scope): 설명`. 설명은 한국어 현재형 "~한다", 마침표 없이, 72자 이하(커밋 규칙 3.2절). 작업 단계 이름
(`라운드 4`, `wave 1`)은 scope로 쓰지 않는다.
- **발견 ID:** 커밋 메시지에 발견 ID를 적는다(`SPEC.md` 36줄). 꼬리말 `Refs: 1103/11-07`처럼 라운드 접두어를 붙인다
(커밋 규칙 3.4절, 가이드 36.3절).
- **CHANGELOG의 리뷰 ID**도 `MMDD/NN-MM` 꼴이어야 한다. `tests/unit/changelog-review-ids.test.ts`가 검사한다.
- **호환을 깨는 변경:** type 뒤 `!`와 `BREAKING CHANGE:` 꼬리말(커밋 규칙 3.2절).
- **본문:** 문제 → 고른 방법과 버린 대안 → 위험·한계 → 검증(커밋 규칙 3.3절). 결함 수정은 「위험·한계」에 그 수정이 새로
가정하는 것을 적는다(01장 2절).
- **AI 꼬리말 금지:** 4.1절 O-4.
- **push·PR:** 수정 세션은 하지 않는다. 총괄이나 리뷰를 맡긴 세션이 한다(09장 6절).
- **PR 크기:** 자기완결적인 변경 하나에 PR 하나. 라운드 전체를 PR 하나로 올리지 않는다(커밋 규칙 5.1절, 표 O-16).
PR 본문은 커밋 규칙 5.3절의 여섯 칸을 쓰고, 「위험과 영향」과 「검증」은 비우지 않는다. merge는 소유자가 한다.
## 지금 이해하면 되는 것
- 결정이 필요해 보이면 이 장 4절과 최근 리뷰 README부터 찾는다. 이미 정한 것은 다시 묻지 않는다.
- 못 고치는 발견은 5절 형식의 결정 대기로 남긴다. 형식을 못 채우면 미완이다.
- 커밋에는 `Refs: MMDD/NN-MM`, AI 꼬리말은 없다.
+168
View File
@@ -0,0 +1,168 @@
# 09. 작업 진행 방식
## 핵심
큰 개선 작업은 **총괄 세션 하나와 하위 세션·서브에이전트 여럿**으로 나눈다. 총괄은 맡기고, 모으고, 다시 확인하고,
멈출지 정한다. 하위 세션은 맡은 영역 하나를 끝까지 한다.
```text
총괄(오케스트레이터)
├─ 리뷰 라운드: 게이트 1회 실행 → 사본 공유 → 영역 리뷰어 16개 → 실험 목록 → 일괄 실행 → README
├─ 수정 라운드: 영역별 수정 세션(격리 worktree·브랜치) → 통합 브랜치에 합침 → merge 게이트 14개
└─ 멈출 조건 판정 → 마지막 Medium·Low 수정 → 보고
```
이 장의 규칙은 2026-11-03~05 사용자 지시와 그때 리뷰 README에 남은 운영 기록이 출처다. 이 장이 그 규칙들의 repo 안
정본이다(README 결정 M-9).
## 1. 역할
| 역할 | 하는 일 | 하지 않는 일 |
| --- | --- | --- |
| 총괄 세션 | 범위·기준 커밋 고정, 게이트 실행, 영역 분할과 brief, 결과 통합, High·새 P1 재확인, 결정 정리, 멈춤 판정, 보고 | 영역 작업을 직접 다 하기. 총괄은 하위 세션에 맡긴다(사용자 지시) |
| 하위 세션 | 맡은 영역의 리뷰 또는 수정. 자기 worktree·브랜치에서 일하고 결과를 보고 | 다른 영역 파일 수정, push·PR, 범위 밖 수정 |
| 서브에이전트 | 한 번에 끝나는 조사·추출·리뷰. 결과를 파일로 남기고 짧게 보고 | 결정, 커밋 |
- 하위 세션이 결정이 필요한 것을 만나면 총괄에 한 번 묻고 기다린다. 스스로 정하지 않는다.
- 짝 백엔드 repo(`clean-architecture-backend-template`)는 읽기만 한다. stage·commit·push하지 않는다(사용자 지시).
백엔드에 넘길 것은 리뷰 README 「남은 문제」에 "백엔드에 넘길 것"으로 적는다(1103 README 14.7절).
## 2. brief 쓰는 법
하위 세션이 아는 것은 brief뿐이다. 다음을 넣는다.
1. 목표 한 문장과 끝났다고 볼 조건.
2. 기준 커밋·브랜치·작업 위치(worktree 경로).
3. 읽을 정본과 지난 기록의 위치(이 매뉴얼 장 번호로).
4. 하지 말 것: 리뷰면 코드 수정, 수정이면 범위 밖 파일·push·PR, 공통으로 짝 백엔드 쓰기.
5. 실행 위치와 잠금(07장 7절).
6. 보고 형식: 바꾼 것, 확인한 것(명령과 결과), 남은 것. 결론을 미리 주지 않는다. 총괄이 만든 변경을 리뷰시킬 때는
코드만 주고 결론은 주지 않는다(1103 README 10.5절 머리말).
## 3. 리뷰 라운드 운영
1. 총괄이 기준 커밋을 고정하고 게이트를 **한 번** 돌린다(07장 3절).
2. 출력과 `artifacts/`·`dist/`·`test-results/`를 읽기 전용 사본으로 뜬다. 4라운드는 desktop의
/tmp/claude-gates/r4/snap/ 에 두었다(1105 README 11.4절).
3. 영역 리뷰어를 병렬로 띄운다. 영역 표는 가장 최근 README의 것을 다시 쓴다(16개 영역, 1105 README 11.2절).
4. 리뷰어는 코드와 사본만으로 판정하고, 더 필요한 실험을 목록으로 낸다(4절).
5. 총괄이 실험을 일괄로 돌리고 결과를 영역에 돌려준다.
6. 총괄이 High 이상·새 P1을 직접 다시 확인하고 README를 쓴다(02장 6절).
## 4. 리뷰 중 실행 — 한 번 돌리고 함께 읽는다
사용자 결정이다: 필요할 때만, 묶어서, 실행마다 환경을 되돌린다(1105 README 11.4절, 2026-11-05).
- **게이트는 한 번.** 리뷰어마다 같은 빌드·테스트를 다시 돌리지 않는다. 4라운드 처음에 영역 리뷰어 16개가 각자
desktop에서 실행하게 했다가 잠금 줄에 30여 건이 섰고 32건을 취소했다(1105 README 11.5절 첫 행).
- **추가 실험은 목록으로.** 항목마다 ID, 명령, env, 시간 상한, 필요하면 변이 패치를 적는다.
- **같은 명령은 한 번만.** 두 영역이 같은 변이를 원하면 한 번 돌리고 결과를 함께 쓴다(1105 README 11.4절 셋째 줄).
- **실험마다 작업 폴더를 되돌린다.** 항목 앞뒤로 추적 파일을 기준 커밋으로 되돌리고 추적 안 된 파일을 지운다
(`node_modules`는 둔다). 4라운드 78항목 모두 `restore=clean`이었다.
- **복제본을 늘려 해결하지 않는다.** 한 checkout에서 두 실행이 부딪히는 원인은 고정 출력 경로·고정 포트라는 템플릿
결함이다(1105/12-04, 부록 P-06). 복제본을 늘리면 그 결함을 가리고 디스크·설치 비용만 는다.
4라운드의 일괄 실행기와 그 사용법은 같은 세션 그룹의 공유 노트에 있다(07장 7절).
## 5. 반복과 종료
### 5.1 반복
리뷰 → 수정 → 다음 라운드 리뷰를 반복한다(2026-11-04 사용자 결정). 라운드 하나의 순서:
1. 수정을 통합 브랜치에 합친다(6절).
2. merge 게이트 14개를 돌린다(07장 3절).
3. 전체 리뷰를 한 번 더 한다. 지난 발견 전부를 ID별로 다시 판정하고 새 발견을 찾는다. 수정 세션의 "고침" 보고를
그대로 믿지 않는다. 1103 조치에서 "고침"으로 적은 것 중 13건이 4라운드에서 "일부"로 정정됐다
(1105 README 3.1절).
4. 발견을 고친다.
- 라운드 사이에 새 기능이나 큰 구조 변경을 넣지 않는다. 넣으면 발견 수가 줄어드는지 볼 수 없다.
- 라운드마다 새 발견 수를 High·Medium·Low와 P1로 나눠 앞 라운드와 비교한다(1105 README 4절 표).
### 5.2 멈출 조건
다음 셋을 모두 채운 라운드에서 멈춘다(2026-11-04 사용자 결정).
1. 그 라운드의 **새 High 0**.
2. 그 라운드의 **새 P1 0**.
3. **merge 게이트 14개 통과**(07장 3절 방법. 고른 스크립트 목록으로 판정하지 않는다).
조건을 채워도 바로 끝내지 않는다. **그 라운드의 Medium·Low를 고치고** 멈춘다. 4라운드(1105)는 새 High 0이지만 새
P1이 3건이고 FE-GATE-013이 desktop에서 실패해 조건을 채우지 못했다(1105 README 2.2절, 11.1절).
멈춤 기준은 repo마다 자기 정본을 따른다. 두 기준을 하나로 맞추지 않는다(2026-11-05 소유자 결정 「각자 유지」,
README 결정 M-7, 08장 표 O-12).
- 백엔드와의 차이는 **마지막 수정이 확인 리뷰를 받는가**다. 백엔드는 리뷰 → 수정 → 확인 리뷰를 발견이 심각도와
상관없이 0이 될 때까지 돌아, 마지막 라운드에서 고친 Medium·Low도 확인 리뷰를 받는다. 프론트는 멈출 조건을 채운
라운드의 Medium·Low를 고치고 멈추므로, 그 마지막 수정은 다음 리뷰를 받지 않는다.
- 그래서 마지막 수정이 새 결함을 만들면(부록 P-26) 리뷰가 아니라 그 수정의 RED·GREEN 테스트와 merge 게이트 14개만이
잡는다. 마지막 수정도 01장 2절 절차(특히 5단계 "템플릿 원래 상태 밖에서도 확인")와 07장 3절 merge 판정을 그대로
거친다.
### 5.3 남은 문제 0으로 보고한다
- 리뷰 발견은 Low까지 고친다. 보고의 "남은 문제"는 0이어야 한다(사용자 지시).
- 수정 결과를 보고할 때 「고침」은 확정이 아니다. 다음 리뷰가 ID별로 다시 판정한다(5.1절 3단계). 보고서에도 "다음
리뷰에서 재판정"이라고 적는다. 1103 조치의 「고침」 13건이 4라운드에서 「일부」로 정정됐다(2026-11-05 사용자 지시,
총괄 세션 전달).
- 고칠 수 없는 것은 **결정 대기**로 남긴다. 이유, 선택지, 결정할 사람을 적는다(08장 4절 형식). "나중에", "범위 밖"
같은 이유 없는 이월은 남기지 않는다.
- 개선 제안(결함이 아닌 것)도 열린 채 두지 않는다. 받아서 하거나, 하지 않는 이유를 결정으로 남긴다.
### 5.4 반복 상한
1103 수정 라운드 뒤로 세 라운드를 더 돌아도 멈출 조건에 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게
보고한다(2026-11-04 사용자 결정). 4라운드(1105)가 그 첫째다. 이 상한은 그동안 repo 밖 작업 메모에만 있었다.
## 6. 수정 라운드 운영
1. 통합 브랜치를 만든다: `fix/maturity-review-<YYYY-MM-DD>`(리뷰 날짜). 예: `fix/maturity-review-2026-11-03`
(1103 README 14.1절).
2. 영역별 수정 세션이 격리 worktree의 `fix/r<MMDD>-<이름>` 브랜치에서 RED 테스트부터 고치고 커밋한다(wave 1).
다른 수정에 기대는 묶음은 그 수정이 합쳐진 뒤 시작한다(wave 2). CHANGELOG·문서는 마지막에 한 세션이 다시 쓴다
(wave 3).
3. 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 빠른 게이트를 돌린다(07장 2절). 합친 뒤에만 생긴 실패는
README 「통합에서 생긴 것」에 커밋과 함께 적는다(1103 README 14.3절).
4. 통합 브랜치에서 merge 게이트 14개를 돌린다. `ci:gate`는 첫 실패에서 멈추므로 고칠 때마다 다시 돌리고, 회차별
결과를 표로 남긴다(1103 README 14.5절).
5. push·PR 본문·최종 보고는 총괄(또는 리뷰를 맡긴 세션)이 한다. 수정 세션은 하지 않는다(1103 README 14절 머리말).
6. **큰 라운드는 작은 PR로 나눈다.** 라운드 전체를 PR 하나로 올리지 않는다. 자기완결적인 변경 하나(예: 영역 수정
브랜치 하나)를 PR 하나로 낸다. 크기는 대략 100줄이 적당하고 1,000줄이면 너무 크다. 리팩터링과 동작 변경은 PR을
나눈다. 기계적으로 만든 큰 변경은 크기 예외로 두고 만든 명령과 기준 커밋을 적는다(커밋 규칙 5.1절). 소유자가 PR을
직접 merge한다(2026-11-05 사용자 지시, 총괄 세션 전달). 직전 라운드는 발견·결정 24건을 Gitea PR 하나(4번, main 커밋 `409d72e`)로
올렸다.
공통 지시(모든 수정 세션의 brief에 넣는다): RED 먼저, 논리적 변경 하나에 커밋 하나, 커밋 규칙, AI 꼬리말 금지,
`corepack pnpm`, 무거운 실행은 공유 잠금(1103 README 14.1절 셋째 줄).
## 7. 소유자 환경
이 절은 이 repo 소유자의 도구에 묶인 규칙이다. 복사한 프로젝트는 이 절을 자기 환경으로 바꾼다(README 결정 M-4).
- 세션 도구: Claude Code 데스크톱 앱. 총괄은 하위 세션을 띄우고, 하위 세션은 막힐 때 총괄에 한 번 묻는다.
- 공유 노트: 같은 세션 그룹은 repo 밖 공유 노트 폴더에 큰 발견과 인계 메모를 남긴다. 메시지에 길게 붙이지 않는다.
예: 4라운드 리뷰 위치·일괄 실행기 사용법, FE-GATE-008 원인 조사 두 건.
- 실행 위치와 잠금: 07장 7절.
- 보고: 작업 완료 보고는 "변경 / 확인 / 남은 문제" 세 줄이다. 소유자의 전역 지시가 정본이다(repo 밖).
## 8. 총괄이 자주 한 실수
리뷰 README의 「오케스트레이터 자신의 실수」 절에서 모았다. 같은 실수를 막는 규칙은 오른쪽 장에 있다.
| 실수 | 결과 | 막는 규칙 |
| --- | --- | --- |
| 게이트 목록을 지난 라운드 목록에서 가져왔다 | 실제 러너에서 항상 실패하는 merge 게이트 둘을 놓쳤다(1103 README 10.5절) | 07장 3절: merge 단계 `gateIds`로 돌린다 |
| 판정 표를 짝 백엔드 문서만으로 정했다 | 업무 거절이 트랜잭션 전에 난다는 사실을 놓쳐 High를 만들었다(1103/03-01) | 04장 4절: 짝 사실은 코드까지 따라간다 |
| 다운스트림 파일을 열지 않고 이름으로 추정했다 | CHANGELOG에 틀린 이행 안내(1103/14-02) | 08장 4절: 확인하지 않은 것은 "미확인"으로 |
| 지운 코드의 실행 동작만 찾았다 | 지운 검사·테스트가 지키던 동작을 놓쳤다(1103/07-01, 10-04) | 04장 5절: 지울 때는 그 코드가 지키던 것을 찾는다 |
| 영역 리뷰어마다 desktop에서 실행하게 했다 | 잠금 줄 30여 건, 32건 취소(1105 README 11.5절) | 4절 |
| `verify:documentation`을 옆 checkout 없는 임시 worktree에서 `pnpm`으로 돌렸다 | pnpm이 재설치를 시도하다 TTY 없음으로 멈춰 결과가 무효(1105 README 11.5절) | 07장 6절 |
| 제거 드릴을 `npm run`으로 돌렸다 | 모든 검사가 `Unknown command`로 실패, 결과를 버렸다(1103 README 10.4절) | 07장 1절: `corepack pnpm`만 쓴다 |
## 지금 이해하면 되는 것
- 총괄은 맡기고 모으고 다시 확인한다. 영역 작업은 하위 세션이 한다.
- 리뷰 중 실행은 총괄이 한 번 돌리고 모두가 함께 읽는다. 추가 실험은 목록으로 모아 일괄로 돌린다.
- 새 High 0·새 P1 0·merge 14개 통과면 그 라운드의 Medium·Low를 고치고 멈춘다. 못 고친 것은 결정 대기로 남긴다.
+152
View File
@@ -0,0 +1,152 @@
# 개선 작업 매뉴얼 — 이 repo를 리뷰·수정·리팩터링·최적화할 때의 기준
## 핵심
이 매뉴얼은 **이미 있는 코드를 평가하거나 고치는 사람**이 읽는다. 사람과 AI 에이전트가 같은 기준을 쓴다.
새 기능을 만드는 순서는 [`docs/manual/`](../manual/README.md)이 맡는다. 두 매뉴얼은 독자가 다르다.
개선 작업 하나는 다음 흐름을 탄다. 괄호 안 숫자는 이 매뉴얼의 장이다.
```text
리뷰(02) ──> 발견 색인 ──> 수정 묶음(01·03·04·05·06) ──> 검증(07)
^ |
| v
└── 다음 라운드 리뷰: 지난 발견 재판정 + 새 발견(02) <── 멈출 조건을 채웠나?(09)
| 새 High 0 · 새 P1 0 · merge 게이트 14개 통과
v
그 라운드의 Medium·Low를 고친다 ──> 결정·결과 기록(08) ──> 보고
```
- **리뷰**는 결함을 찾고 적는다. 코드를 고치지 않는다(`CLAUDE.md` 「리뷰 기준」).
- **수정 묶음**은 결함을 테스트로 먼저 재현하고(RED) 고친다(GREEN).
- **다음 라운드 리뷰**는 지난 발견이 정말 고쳐졌는지 다시 판정하고, 수정이 만든 새 결함을 찾는다.
4라운드 리뷰의 새 발견 48건 중 상당수가 지난 수정에서 나왔다(1105 README 4절 끝 목록).
- 멈추는 조건과 그 뒤에 할 일은 09장 5절이 정한다.
## 적용 범위
| 작업 | 이 매뉴얼 | 다른 문서 |
| --- | --- | --- |
| 리뷰(전체·영역·PR·diff) | 01장 1절, 02장 | `CLAUDE.md` 「리뷰 기준」, 리뷰 가이드(아래) |
| 결함 수정 | 01장 2절, 04·05장 | `SPEC.md` 「공통 완료 기준」 |
| 리팩터링(동작을 바꾸지 않는 구조 변경) | 01장 3절, 04장 | 리뷰 가이드 39절 |
| 성능 최적화 | 01장 4절, 06장 | `docs/operations/performance-evidence.md` |
| 폴더·모듈 구조 변경 | 01장 5절, 03장 | `docs/architecture/layers.md`, `.dependency-cruiser.json` |
| 테스트 구조 개선 | 01장 6절, 05장 | `docs/testing/taxonomy.md` |
| 새 기능 추가 | 아님 | [`docs/manual/`](../manual/README.md) |
| 운영 장애 대응 | 아님 | `docs/runbooks/`, `docs/operations/` |
## 정본 표
이 매뉴얼은 규칙을 다시 쓰지 않고 **정본을 가리킨다**. 매뉴얼과 정본이 다르면 정본이 맞고, 매뉴얼을 고친다.
맨 아래 「이 매뉴얼이 정본」 행만 이 매뉴얼이 처음이자 유일한 기록이다.
| 무엇 | 정본 | 이 매뉴얼에서 |
| --- | --- | --- |
| 리뷰 기준, 이 repo의 리뷰 전제 4개, 전체 리뷰 절차 5단계 | 루트 `CLAUDE.md` 7~30줄. 루트 `AGENTS.md`는 추적하지 않는 사본이다(08장 결정 M-10) | 01장 1절, 02장이 가리킴 |
| 28개 관점, 판정 체계(성격·심각도·우선순위·통제·증거), 발견·요약·판정표 양식 | `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` 0~36절, 실행 순서는 `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md` | 02장이 이 repo에 맞춤 |
| 수정 라운드의 공통 완료 기준 9개 | `SPEC.md` 27~37줄 | 01장 2절, 07장이 가리킴 |
| 최상위 `src/` 폴더의 역할, 계층 규칙, adapter kernel | `docs/architecture/layers.md` | 03장이 가리킴 |
| import 규칙과 kernel 예외 | `.dependency-cruiser.json`(`check:architecture`가 읽는다) | 03장이 가리킴 |
| adapter 목록 | `docs/reviews/adapters/INVENTORY.md`(`check:adapter-inventory`, FE-GATE-010) | 03장이 가리킴 |
| 게이트 ID·단계·명령 | `config/ci/gates.json`, 설명은 `docs/operations/ci-quality-gates.md` | 07장이 언제·어디서 돌릴지 정함 |
| 테스트 층과 테스트 위치 | `docs/testing/taxonomy.md`, 넓은 설계는 `docs/testing/frontend-platform-testing-strategy.md` | 05장이 가리킴 |
| 성능 예산과 기준선 | `config/performance/budgets.json`, `docs/operations/performance-evidence.md` | 06장이 측정 조건을 더함 |
| 규모 설계(예산·실행·텔레메트리) | `docs/architecture/scale-architecture.md` | 04·06장이 `scale-architecture.md §N`으로 가리킴 |
| 새 기능 만드는 순서 | `docs/manual/` | 가리킴 |
| 문서 색인과 문서 검사 범위 | `docs/README.md`, 검사 규칙은 `scripts/verify-documentation-readiness.ts` | 07장이 가리킴 |
| 커밋·PR 형식 | `design-docs/conventions/commit-and-pr.md`(repo 밖, 이 repo 옆 `design-docs` repo) | 08장이 이 repo에서 쓰는 꼬리말을 덧붙임 |
| 소유자 결정 원문 | 각 리뷰 README의 「결정이 필요한 것」「조치」 절, `SPEC.md` 「결정」, `docs/architecture/decisions/` | 08장은 색인 |
| **이 매뉴얼이 정본** | 작업 종류별 절차(01), 이 repo의 리뷰 점검 항목·결함 판정 예·리뷰 문서 형식(02), 반복 결함 패턴과 막는 기준(04·05·부록), 성능 측정 조건(06), 무거운 실행 위치와 merge 판정 방법(07), 결정 기록법(08), 세션 분업·리뷰 중 실행 방식·반복 종료 조건(09) | |
## 읽는 순서
처음이면 이 README → 01 → 09 → 07을 읽는다. 그다음은 맡은 작업의 장만 읽는다.
| 장 | 파일 | 언제 읽나 |
| --- | --- | --- |
| 01 작업 종류별 절차 | [01-procedures.md](01-procedures.md) | 어떤 작업이든 시작할 때. 시작 조건·단계·산출물·완료 기준 |
| 02 리뷰 기준 | [02-review-criteria.md](02-review-criteria.md) | 리뷰하거나 리뷰 결과를 읽을 때 |
| 03 폴더·모듈 구조 기준 | [03-folder-module-structure.md](03-folder-module-structure.md) | `src/` 폴더·adapter 그룹·기능 폴더·문서 위치를 바꿀 때 |
| 04 코드 구조 기준 | [04-code-structure.md](04-code-structure.md) | 결함을 고치거나 리팩터링할 때 |
| 05 테스트 구조 기준 | [05-test-structure.md](05-test-structure.md) | 테스트를 쓰거나 옮기거나, 가끔 떨어지는 테스트를 조사할 때 |
| 06 성능·최적화 기준 | [06-performance.md](06-performance.md) | 성능을 재거나 고칠 때 |
| 07 검증과 게이트 | [07-verification-gates.md](07-verification-gates.md) | 무엇을 언제 어디서 돌릴지, merge 가능을 어떻게 판정할지 정할 때 |
| 08 결정과 기록 | [08-decisions-records.md](08-decisions-records.md) | 결정이 필요해 보일 때, 커밋·PR을 쓸 때 |
| 09 작업 진행 방식 | [09-working-method.md](09-working-method.md) | 여러 세션으로 나눠 일할 때, 반복을 멈출지 정할 때 |
| 부록 결함 패턴 카탈로그 | [appendix-defect-patterns.md](appendix-defect-patterns.md) | 리뷰 전에 훑어볼 목록이 필요할 때 |
## 백엔드 매뉴얼과 같은 뼈대
짝 백엔드 템플릿(`clean-architecture-backend-template`)도 같은 장 번호와 같은 파일 이름으로 개선 매뉴얼을 둔다.
장 번호가 같으면 "두 repo의 05장"처럼 같은 주제를 바로 비교할 수 있다. 이 repo는 장을 합치거나 더하지 않았다.
장 이름과 파일 이름은 2026-11-05 백엔드 매뉴얼 초안의 「읽는 순서」 표에 맞췄다(결정 M-2).
백엔드와 내용이 다른 곳은 정본이 달라서다. 예: 백엔드의 규칙 정본은 `AGENTS.md`와 registry지만, 이 repo의 정본은
`CLAUDE.md`·`SPEC.md`·`config/ci/gates.json`·`.dependency-cruiser.json`이다.
## 리뷰 가이드와의 관계
리뷰 기준은 `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`(이하 「가이드」)다. Backend·Frontend·Platform 공용
일반론이고, 예시는 이 repo의 코드가 아니다.
- 이 매뉴얼은 가이드를 **복사하지 않는다**. 「가이드 35.5절」처럼 절 번호로 가리킨다.
- 02장은 가이드의 28개 관점과 판정 체계를 **이 repo의 경로·명령·지난 결함**으로 바꿔 적는다.
- 가이드는 복사한 프로젝트가 지워도 되는 `docs/reviews/` 안에 있다(루트 `README.md` 「Files you can delete after
copying」). 가이드를 지운 프로젝트도 02장만으로 판정할 수 있게 썼다.
## 근거 표기
- 경로는 repo 루트 기준이다. 코드 근거는 `file:line`, 문서 근거는 「문서 N절」로 적는다.
- 리뷰 ID는 가이드 36.3절의 라운드 밖 표기 `MMDD/NN-MM`을 쓴다. 이 매뉴얼에서 쓰는 줄임말:
| 줄임말 | 뜻 |
| --- | --- |
| `0925/03-01` | `docs/reviews/2026-09-25-maturity-review/`의 발견 03-01 |
| `0929/03-03` | `docs/reviews/2026-09-29-maturity-review/`의 발견 |
| `1101/12-04` | `docs/reviews/2026-11-01-maturity-review/`의 발견. 「1101 README」는 그 폴더의 `README.md` |
| `1103/11-07` | `docs/reviews/2026-11-03-maturity-review/`의 발견 |
| `1105/12-04` | 4라운드 리뷰(2026-11-05)의 발견. 이 매뉴얼을 쓸 때 main에 없고 브랜치 docs/maturity-review-2026-11-05의 커밋 `e85c836`에만 있다. 합쳐지면 docs/reviews/2026-11-05-maturity-review/에 놓인다 |
| 「가이드 N절」 | `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`의 N절 |
| 「커밋 규칙 N절」 | repo 밖 `design-docs/conventions/commit-and-pr.md`의 N절 |
- 백틱 안의 repo 경로는 `verify:documentation`이 있는지 검사한다(07장 6절). 아직 main에 없는 4라운드 리뷰의 경로만
백틱 없이 쓴다. 참조 기능과 함께 지워지는 경로는 이름을 쓰지 않고 그 경로를 소유한 문서의 절을 가리킨다.
- `file:line`은 낡는다(부록 P-43). 이 매뉴얼은 줄 번호를 잘 바뀌지 않는 정본(`CLAUDE.md`, `SPEC.md`, 가이드)과 리뷰
기록(고치지 않는 문서)에 주로 쓴다. 자주 바뀌는 코드 파일은 파일과 심볼 이름으로 가리킨다.
- **리뷰 ID는 출처 표시다.** 규칙 문장은 리뷰 문서 없이도 뜻이 통하게 썼다. 복사한 프로젝트가 `docs/reviews/`를
지워도 기준은 남는다.
- 이 repo에서 근거를 찾지 못한 기준은 **[제안]**으로 표시했다. 제안은 소유자가 받기 전까지 규칙이 아니다.
## 결정 기록
이 매뉴얼을 만들며 정한 것이다. 소유자가 뒤집을 수 있다. 소유자 결정 전체의 색인은 08장이다.
| # | 결정 | 이유 | 버린 대안 |
| --- | --- | --- | --- |
| M-1 | 위치는 `docs/improvement/` | 독자가 `docs/manual/`(새 기능 작성자)과 다르다. `docs/reviews/`는 지워도 되는 작업 이력이라, 기준서를 섞으면 어느 문서가 현재 기준인지 흐려지고 복사본에서 함께 지워진다 | `docs/reviews/` 안에 두기, `docs/manual/` 뒤에 장 추가 |
| M-2 | 장 번호·이름·파일 이름은 백엔드 매뉴얼과 같다 | 두 repo의 같은 장을 바로 비교하게 한다. 백엔드 총괄 세션에 2026-11-05 알렸다 | 07·09 합치기, 프론트만의 장 추가 |
| M-3 | `docs/README.md` §1에서 이 폴더를 링크한다 | `verify:documentation`이 이 폴더 `.md`의 repo 경로·package script·FE-GATE ID가 있는지 검사하게 된다. 같은 검사가 FE-GATE-005·020 안에서도 돌므로 merge 때마다 확인된다. 정본을 가리키는 문서라 가리킨 곳이 없어지면 바로 알아야 한다. 대가: main에 없는 경로와 샘플과 함께 지워지는 경로는 백틱으로 쓸 수 없다 | §3 작업 이력에 두기(검사 밖), 검사 코드에 목록 추가(이 작업은 문서만 바꾼다) |
| M-4 | 복사 뒤 지워도 되는 문서 목록에 넣지 않는다 | 복사한 프로젝트도 리뷰·수정·최적화를 한다. 소유자 환경에 묶인 규칙은 07장 7절과 09장 7절 「소유자 환경」에만 두어, 복사본은 그 두 절만 바꾸면 된다 | 루트 `README.md` 삭제 목록에 추가 |
| M-5 | 심각도 체계는 가이드 35.2절(Critical~Low)과 35.3절(P0~P3) 하나만 쓴다 | 이 repo의 다섯 라운드가 모두 이 체계로 적혔다. 백엔드는 확인 리뷰에 Critical/Important/Minor를 더 쓰지만, 이 repo에는 그 이력이 없다. 소유자 지시의 "Minor"는 Low로 읽는다(09장 5절) | 백엔드처럼 두 체계 |
| M-6 | 08장의 결정 표는 색인이다. 한 줄 요약과 출처만 둔다 | 결정 원문을 옮겨 쓰면 갈라진 복사본이 된다(부록 P-14) | 결정 원문 이동 |
| M-7 | 반복 종료 조건은 소유자 문장 그대로 쓴다(09장 5.2절) | 2026-11-04 사용자 결정의 문장이다. 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 차이는 마지막 라운드의 Medium·Low 수정이 확인 리뷰를 받는가다(프론트는 받지 않는다). 2026-11-05 소유자 결정 「각자 유지」가 두 기준을 각자 유지하게 정했다(08장 표 O-12) | 백엔드 문장으로 통일 |
| M-8 | repo 밖 문서(커밋 규칙, 백엔드 매뉴얼)는 링크 대신 평문이나 코드 표기 | `verify:documentation`은 repo 밖 링크를 옆 checkout에서 찾는다. 옆 checkout이 없거나 다른 커밋이면 결과가 기계마다 달라진다(1105/12-02) | 상대 링크 |
| M-9 | "Low도 고친다", "총괄은 하위 세션에 맡긴다", "리뷰 중 실행은 한 번 돌리고 함께 읽는다"는 2026-11-03~05 사용자 지시다. 09장이 이 규칙들의 repo 안 정본이 된다 | 규칙이 세션 기록과 리뷰 README 곳곳에만 있었다 | |
| M-10 | 루트 `AGENTS.md`는 건드리지 않는다 | main checkout에 추적하지 않는 파일로 있고(`git ls-files AGENTS.md`가 비어 있다) 내용은 `CLAUDE.md`와 같다. 추적 대상이 아니라 이 작업의 범위 밖이다 | `AGENTS.md`도 고치기 |
## 이 매뉴얼을 고칠 때
- 정본이 바뀌면 이 매뉴얼의 해당 문장을 고친다. 설명이 정본과 맞는지는 검사하지 않는다. `verify:documentation`은
경로·script·게이트 ID가 있는지만 본다(`docs/README.md` §1 끝 문단).
- 리뷰 라운드에서 새 반복 패턴이 나오면 부록에 행을 더하고, 막는 기준이 생기면 04·05·07장에 넣는다.
- 새 소유자 결정이 생기면 08장 색인에 한 줄을 더한다.
- 4라운드 리뷰가 main에 합쳐지면 위 줄임말 표의 `1105` 행과 08장 출처를 실제 경로로 바꾼다.
## 지금 이해하면 되는 것
- 새 기능은 `docs/manual/`, 이미 있는 코드를 평가·수정하는 일은 이 매뉴얼.
- 규칙의 정본은 `CLAUDE.md`·가이드·`SPEC.md`·`config/ci/gates.json`·`.dependency-cruiser.json`이다. 이 매뉴얼은
가리키고, 절차·점검 항목·패턴·실행 방식·기록법만 소유한다.
- 리뷰 → 수정 → 다음 라운드 리뷰를, 새 High 0·새 P1 0·merge 게이트 14개 통과까지 돈다. 그 라운드의 Medium·Low를
고치고 멈춘다.
@@ -0,0 +1,110 @@
# 부록. 결함 패턴 카탈로그
## 핵심
2026-09-24 src 리뷰와 성숙도 리뷰 다섯 라운드(0925·0929·1101·1103·1105)에서 **같은 모양으로 두 번 이상 나온 결함**을
모았다. 리뷰 전에 이
목록을 훑으면, 지난 라운드가 이미 본 모양을 빨리 알아본다. 고칠 때는 「막는 기준」 칸의 장을 따른다.
- **ID**는 이 부록의 번호 `P-NN`이다. 다른 장이 이 번호로 가리킨다.
- **대표 발견**은 리뷰 ID(`MMDD/NN-MM`)다. 같은 발견을 두 행의 대표로 쓰지 않았다. 다른 행과 겹치면 그 행을 적었다.
- **관점**은 대표 발견들의 리뷰 문서 「관련 관점」 칸에서 많이 나온 번호다. 칸이 없으면 비웠다.
- 「막는 기준」이 「없음」이면 지난 리뷰에서 일반 기준이 정해지지 않았다는 뜻이다. 그 행을 다시 보면 리뷰는 기준을
제안해야 한다.
- 출처: 2026-11-05에 두 서브에이전트가 리뷰 문서에서 뽑고 줄 번호를 확인한 목록. 1103 이전은 0924·0925·0929·1101
README와 High 영역 문서, 1103·1105는 README와 영역 문서 전부를 읽었다.
Critical은 다섯 라운드 모두 0건이다. 패턴에 들지 않은 High는 0929/09-01(= 1101/09-01, 공개 API가 세션 상태 때문에
전송되지 않음) 하나다.
## 1. 게이트·CI·검증 절차
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
| --- | --- | --- | --- | --- | --- |
| P-01 | 돌리는 게이트 목록이 stage 전체가 아니거나, 게이트가 늦은 단계에서만 돈다 | 리뷰·드릴이 손으로 적은 명령 목록을 돌려 merge 게이트 일부가 빠진다. release 단계 게이트를 아무도 안 돌린다. CI가 꺼져 있다 | 0925/12-01, 0925/12-02, 1101/15-01, 1103/12-02, 1105/12-03 | 07장 2·3절. 리뷰 절차의 게이트 목록은 merge 단계 `gateIds` 전부를 `ci:gate`로 돌리는 것으로 바꿨다(`CLAUDE.md` 27줄, 1105/12-03) | 21, 10, 26 |
| P-02 | 게이트·수정 확인이 템플릿 원래 상태와 작은 입력만 본다 | 기능 0개, 제품 파일이 빈 상태, 객체 0~1개에서만 맞다. 기능을 더하거나 제품 파일을 채운 다운스트림에서 깨진다 | 0925/09-01, 1103/12-01, 1103/16-09, 1105/09-01, 1105/16-03 | 01장 2절 5단계, 05장 3.3절 | 10, 21, 25, 3, 20 |
| P-05 | workflow env에서만 나는 게이트 실패 | `CI=true`·빌드 식별값이 테스트 기대값·dev server·테스트 안 빌드로 새어 실제 CI에서만 실패 | 1103/11-06, 1103/11-07, 1103/11-08 | 07장 3·4절, 04장 6절 | 21, 10, 18, 19 |
| P-06 | 고정 출력 경로·포트·추적 파일에 쓴다 | `dist/`, `artifacts/`, 고정 포트, 커밋된 파일에 써서 한 checkout의 두 실행이 부딪히고 추적 파일이 바뀐다 | 1105/12-04, 1103/12-08, 1105/16-01, 0929/14-01, 0925/00-01 | 실행 격리는 결정 대기(08장 5.1절 D6). 그동안 09장 4절 방식으로 하나씩 돈다. 실행 뒤 `git status`가 비어야 한다 | 20, 25, 12, 10 |
| P-07 | 사전 점검·앞 단계는 PASS인데 본 단계가 실패한다 | 점검이 본 단계와 다른 방법으로 확인해, 전제가 깨진 곳에서 PASS 뒤 원인 없는 원문 오류가 난다 | 1103/11-04, 1105/12-01, 0929/06-01, 1101/09-06 | 07장 5절 | 21, 20, 8, 18 |
| P-08 | 게이트가 호스트·checkout 조건을 말없이 가정한다 | 글꼴 패키지, 옆 백엔드 checkout, user namespace를 적지도 확인하지도 않아 기계마다 결과가 다르다 | 1103/11-02, 1105/12-02, 1101/11-02 | 05장 4절, 07장 6절 | 21, 20, 19, 17 |
| P-09 | 거짓 PASS — 검사가 실제 대상과 비교하지 않는다 | 검사가 자기 산출물, 이전 release, 상수 `true`, 오류 화면, fixture 전용 규칙을 보고 통과한다 | 0925/11-01, 1101/13-01, 1103/11-01, 1103/12-04, 1103/13-01, 1105/11-01, 1105/06-02 | 확인 못 한 판정은 `UNVERIFIED`(`SPEC.md` D-14). 05장 3.4절 | 21, 18, 10, 5 |
| P-10 | 정적 검사가 문자열·정규식·이름 모양으로 판정한다 | 코드 구조 대신 정규식·접두어·파일 목록으로 판정해 오탐·미탐이 난다 | 0929/08-02, 0929/07-06, 1101/12-01, 1101/12-03 | import 규칙은 그래프 규칙으로(`SPEC.md` D-12). 문구 검사는 ESLint 구문 규칙으로(1101 README 14.1절 0929/08-02 행) | 21, 10, 23, 24 |
| P-11 | 검사기 자신을 지키는 음성 fixture가 없다 | 규칙을 통째로 꺼도 게이트가 통과한다. 검사기가 0개 모듈을 보고 통과한다 | 1101/12-02, 0925/12-05, 0929/11-08, 1101/14-05 | 통제는 통과 fixture와 거절 fixture가 둘 다 있어야 검증된다(`docs/testing/taxonomy.md` 108~110줄) | 21, 10, 24 |
| P-12 | 항상 실패하거나 통과할 수 없는 게이트를 방치한다 | main에서 항상 실패하지만 CI가 꺼져 있어 아무도 막히지 않고 라운드를 넘긴다 | 0929/11-01, 1101/11-01, 0929/11-02, 1103/12-09 | 사용자 피해가 없어도 Medium·P1로 매겨 첫 묶음에 넣는다(02장 2절) | 21, 10, 26 |
| P-24 | 제거 드릴이 제거와 무관하게 실패하거나 제거 뒤 상태를 안 본다 | 드릴마다 복사·제외 목록을 따로 들어 문서를 빠뜨린다. 예제를 지운 상태는 아무 게이트도 돌지 않는다 | 1103/02-06, 1103/14-04, 1103/16-02, 1105/14-01 | 제외 목록 하나(`scripts/lib/removal-fixture.ts`). 03장 6절 | 27, 21, 10, 20 |
| P-25 | 게이트 출력·로그에 실패 원인이 남지 않는다 | "실패"만 남고 넘은 한도·reason·로그는 버려지거나 올라가지 않는다 | 0925/12-11, 1101/14-06, 1103/14-06, 1103/15-03, 1105/13-01 | 예산 검사는 넘은 항목·값·초과량을 출력한다. release job 로그 업로드는 미조치(1105/13-01) | 8, 20, 5 |
| P-26 | 수정이 새 결함을 만든다 | 고친 커밋이 새 가정(빈 제품 파일, CI env 없음)을 들이거나 다른 검사를 약하게 한다 | 1103/11-08, 1105/09-01, 1105/09-02, 1105/14-03 | 04장 9절 | 21, 10, 3 |
| P-27 | 완료 기준을 돌리지 않고 "고침"으로 닫는다 | 코드가 들어가면 완료 기준 실행 없이 "고침"으로 적는다. 다음 라운드에 "일부"로 정정된다. 1103 조치의 "고침" 13건이 그랬다 | 1103/05-01, 1103/16-01, 1103/11-02, 1103/11-03 | 가이드 35.6절. 02장 5절, 09장 5.1절 | 10, 21 |
## 2. 테스트
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
| --- | --- | --- | --- | --- | --- |
| P-13 | 규칙을 지워도·결함을 고쳐도 테스트가 그대로 통과한다 | 보호 규칙을 지우는 변이, 판정 경계를 바꾸는 변이가 살아남는다. 커버리지 100%인 곳도 있다 | 1101/07-06, 1101/02-04, 1103/10-02, 1103/07-02, 1105/02-04, 1105/01-04 | RED 먼저(`SPEC.md` 29~30줄), 변이 확인(05장 3.2절). 판정 규칙의 변이 도구는 미조치(1105/10-03) | 10, 21, 6 |
| P-15 | 단언이 대상에 닿지 않아 항상 참이다 | fixture가 비어 첫 줄에서 return하거나 전제를 만들지 않는다. 로딩 화면·fixture 자신을 검사한다 | 1101/10-01, 1101/10-02, 0925/08-05, 0925/11-05 | 05장 3.4절. 전역 `expect.hasAssertions()`는 제안만 됐다 | 10, 21, 24 |
| P-16 | 시간·속도·준비 상태를 가정한 테스트 | 기본 대기, 짧은 상한, 실제 시계, 짧은 전이 상태 폴링에 기대 부하가 있는 호스트에서 실패한다 | 0929/10-01, 1103/10-01, 1103/11-03, 1103/11-05, 0929/11-04 | 공통 대기 기한은 `tests/setup.ts` 한 곳. 05장 5절 | 10, 21, 12 |
| P-17 | 브라우저의 추정에 기댄다 | WebKit이 load 3초 뒤 한 번 하는 preload 추정에 기대 곧 쓰일 preload로 실패하고, 정말 안 쓴 preload는 놓친다. 같은 원리로 두 spec이 떨어졌다 | 1103/11-09 | 추정 대신 확인하려는 사실을 직접 검사한다(05장 5.3절) | 10, 21 |
| P-18 | 그리는 중인 화면을 누른다 | 앱 뒤에 붙인 버튼이 렌더링 중 밀려 클릭이 닿지 않는다. 같은 파일의 두 test가 떨어졌다 | 1103/11-10 | 테스트가 붙이는 조작 요소는 고정 층에(05장 5.3절) | 10, 21 |
| P-19 | 테스트 대역이 실제 상대와 다르다 | 메모리 IndexedDB, fake, 백엔드 문서에서 옮긴 MSW 응답이 실제와 달라 결함을 숨긴다 | 0925/05-08, 0925/06-01, 1103/05-04, 1103/16-01, 1105/01-01 | 실제 짝 백엔드 응답으로 맞추기는 미조치(1105 README 9절) | 10, 17, 12 |
| P-20 | 플랫폼 테스트가 샘플·특정 파일·예시 이름에 묶인다 | 샘플을 지우면 테스트가 같이 사라지거나 게이트가 깨진다. 템플릿 테스트의 글자가 매뉴얼 예시 기능 이름과 부딪힌다 | 0925/14-01, 0929/10-02, 1101/16-02, 1105/10-01, 1105/16-04 | 테스트 전용 라우트와 플랫폼 소유 MSW 카탈로그(05장 2절). 탐침 이름은 예약 접두어 `typecheck-probe-*` | 27, 10, 21, 20 |
| P-21 | 빠른 계층에 느린 테스트가 섞인다 | unit에 프로세스를 띄우는 도구 테스트, 실제 시계로 기다리는 테스트가 섞이고 같은 파일을 두 번 돈다 | 1101/10-05, 1101/10-06, 1101/10-07, 1101/15-04 | 없음. 05장 6절 | 14, 20, 10 |
| P-22 | 깨끗한 clone·다른 호스트에서 실패한다 | gitignore된 생성물, 기준선을 만든 CPU, 실행기가 넣는 npm 환경변수에 기댄다 | 0924 6.0절, 0925/10-01, 0925/11-03, 1101/15-05 | 한 파일 실행도 `scripts/run-vitest.ts`로(07장 1절). merge 판정은 깨끗한 checkout에서(07장 3절) | 10, 21, 20 |
| P-23 | 지우거나 바꾼 코드가 지키던 검사·테스트를 같이 잃는다 | 삭제·이름 변경이 실행 동작만 옮기고, 지운 행·테스트가 지키던 규칙은 옮기지 않는다 | 1103/07-01, 1103/10-04, 1105/04-01, 1105/10-01 | 04장 5절 | 10, 21, 17 |
## 3. 코드
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
| --- | --- | --- | --- | --- | --- |
| P-28 | 실패를 다른 종류로 분류해 복구 경로가 닫힌다 | status 하나나 표 밖 기본값으로 판정해 업무 거절·입력 오류·일시 오류·서버 장애가 뒤섞인다 | 0925/03-02, 0929/03-05, 1103/03-01, 1105/01-01, 1105/04-02, 1105/03-02 | 04장 2절 | 6, 17, 8, 24 |
| P-29 | 결과 불명 쓰기를 무방비로 다시 보낸다 | 적용됐을 수 있는 쓰기를 키 없이, 새 키로 다시 보내는 입구가 남는다. 고칠 때마다 다른 입구에서 나온다 | 0925/03-01, 0929/03-01, 0929/03-03, 1103/03-03, 1103/04-01, 1105/01-02, 1105/03-01 | 04장 2절, `docs/manual/02-decision-tables.md` 3·4절 | 6, 17, 12, 28 |
| P-30 | 오지 않을 신호를 기다리며 멈춘다 | 재시도 상태 기계가 그 상황에서 오지 않는 신호(새 online 이벤트, 예산 재충전)를 기다려 재시도도 종료도 없이 멈춘다 | 0925/04-01, 0929/04-01, 0929/04-04 | 04장 3절 | 6, 28, 5 |
| P-31 | 손상 한 건이 목록·작업 전체를 멈춘다 | 행 하나가 손상되면 목록 읽기·purge·GC가 그 뒤로 계속 같은 곳에서 실패한다 | 0925/05-02, 0925/05-05, 0929/05-01, 0929/02-01 | 04장 3절 | 6, 28, 11 |
| P-32 | 결과·상태를 실제와 다르게 보고한다 | 다 하지 못했는데 `COMPLETED`·`verified`·`active`를 보고한다. 겹치는 작업 사이 틈을 놓친다 | 0929/05-02, 0925/02-05, 1101/09-07, 1103/05-01, 1103/02-04 | 04장 3절 | 24, 11, 12, 5 |
| P-33 | 실패가 원인·추적값을 버린다 | 서로 다른 실패를 같은 reason으로 남기거나 `traceId`·effect를 싣지 않는다. 새 모듈에서 같은 누락이 다시 생긴다 | 0925/09-04, 1101/02-05, 1103/03-05, 1103/03-06, 1105/01-03, 1105/02-01 | 04장 3절 | 8, 24, 7 |
| P-34 | router base path를 무시한 URL | 하위 경로에 배포하면 `/`부터 조립한 URL이 앱 밖을 가리킨다. 한 곳을 고치면 다른 소비자에서 나온다 | 0925/13-07, 0929/06-02, 1101/06-01 | 04장 6절 | 19, 18, 23 |
| P-35 | 같은 설정을 경로마다 다르게 읽는다 | 번들·빌드 스크립트·SW 빌드가 같은 설정을 다른 출처에서 읽는다 | 0925/09-02, 0925/06-10, 0929/13-02 | 04장 6절 | 19, 18, 23 |
| P-36 | 여러 탭·동시 실행 경쟁 | 두 탭이 같은 저장소·구독·잠금을 건드려 진행 중 데이터를 지우거나 잠금을 무기한 쥔다 | 0925/05-01, 0925/06-02, 0925/05-07, 1103/05-02 | 04장 7절, `SPEC.md` D-3·D-4 | 12, 6, 11 |
| P-37 | 이름 하나가 여러 뜻, 뜻 하나가 여러 이름 | 같은 이름이 다른 모양·뜻을 가리키거나 한 개념을 여러 이름으로 적는다 | 0929/09-04, 1101/07-01, 1101/07-05, 1101/04-02 | 04장 5절(`@deprecated` 별칭) | 24, 23, 4 |
| P-38 | 실패·복구 전이 뒤 화면이 다음 행동을 잃는다 | 한 전이에서 고친 포커스·안내를 다른 전이에 쓰지 않아 키보드 사용자가 위치를 잃거나 버튼이 무반응으로 남는다 | 1103/08-02, 1105/08-01, 1105/08-02, 1105/08-04, 1103/09-11 | 04장 3절 | 1, 6, 24, 28 |
## 4. 구조
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
| --- | --- | --- | --- | --- | --- |
| P-03 | 같은 사실을 repo 안 여러 곳에 손으로 적는다 | 스키마 메타, 레지스트리 행, 허용 키, 빌드 입력 목록을 원본과 따로 적고 대조 검사가 없다 | 1101/07-02, 0929/07-05, 1103/16-04, 1103/13-04, 1105/15-03, 1105/05-01 | 04장 4절 | 23, 17, 3, 21 |
| P-04 | 두 템플릿 사이 계약을 문서 문장·손 사본으로 맞춘다 | 짝 백엔드의 프로토콜·오류 code·응답 모양·생성기 규칙을 프론트 문서·JSON·문자열로 옮기고 게이트가 어긋남을 알리지 않는다 | 1103/01-01, 1103/12-06, 1103/04-02, 1105/07-01, 1105/16-02 | 04장 4절, 1103 결정 D6 | 17, 26, 21 |
| P-14 | 갈라진 중복 복사본 | 같은 로직·fixture·helper·port를 두 벌 이상 두고 이미 규칙이 서로 다르다 | 0924 5.1절, 0925/09-12, 0929/05-03, 1101/07-03, 1101/10-08 | `CLAUDE.md` 19줄, 03장 2절, 04장 4절 | 9, 23, 22 |
| P-39 | 제품이 템플릿 소유 파일을 고쳐야 한다 | 제품마다 다른 것이 템플릿 소유 파일에만 있어 동기화마다 충돌한다 | 0929/09-02, 0929/14-03, 1103/02-01, 1103/12-07, 1105/13-02 | 04장 8절. 1101 결정 「확장 지점을 템플릿이 연다」 | 3, 25, 22 |
| P-40 | 경계·kernel 예외가 실제 쓰임보다 넓다 | 예외가 필요한 것보다 넓게 열려 있거나 공유 메커니즘이 아닌 파일이 kernel 예외를 받는다 | 0925/12-07, 0929/02-06, 1101/05-04 | `CLAUDE.md` 21줄, 03장 2절 | 2, 22, 21 |
| P-41 | 연결된 두 모듈의 약속이 어긋난다 | 모듈마다 테스트는 있지만 한쪽이 보내는 결과를 다른 쪽이 다른 뜻으로 받는다 | 0929/04-02, 1101/04-01, 1101/03-04 | 없음. 04장 8절 | 17, 22, 4 |
## 5. 문서
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
| --- | --- | --- | --- | --- | --- |
| P-42 | 문서의 주장·숫자·상태가 코드와 갈라진다 | 운영 문서가 없는 동작을 안내하거나, 손으로 적은 기준선·상한·상태가 다음 변경에서 낡는다 | 0925/06-03, 1101/01-01, 1103/15-02, 1103/14-01, 1105/04-03 | 숫자는 한 곳에 두고 문서는 그곳을 가리킨다(06장 5절). `verify:documentation`은 경로·이름만 본다(07장 6절) | 9, 5, 24, 26 |
| P-43 | `file:line`·이력 문서 참조가 낡는다 | 줄 번호 참조가 코드 변경으로 밀려 다른 코드를 가리킨다. 결정 근거를 지워도 되는 이력 문서로만 가리킨다 | 0929/02-04, 1101/05-05, 1101/14-01 | 현재 계약 문서는 이력 문서에 기대지 않는다(03장 4절). 이 매뉴얼의 표기 원칙은 README 「근거 표기」 | 9, 4, 24 |
| P-44 | 매뉴얼·안내를 그대로 따르면 게이트가 실패한다 | 매뉴얼 예시, CHANGELOG 이행 단계, 오류 안내를 글자 그대로 따라 한 제품이 merge 게이트에서 실패한다 | 1105/14-02, 1103/14-02, 1103/09-07 | 매뉴얼만 보는 기능 추가 재실험(1103 README 14.6절). 문서 예시를 게이트가 실행하는 기준은 없음 | 20, 19, 9 |
| P-45 | CHANGELOG [계약] 표시가 실제 변경과 다르다 | [계약] 행이 실제 경로·대상과 다르거나 게이트를 좁힌 변경에 표시가 없다 | 0929/02-03, 0929/07-07, 0929/14-04, 1101/14-02 | 리뷰 ID 형식은 `tests/unit/changelog-review-ids.test.ts`. [계약] 표시 기준은 없음 | 9, 17, 26 |
## 6. 성능
| ID | 패턴 | 모양 | 대표 발견 | 막는 기준 | 관점 |
| --- | --- | --- | --- | --- | --- |
| P-46 | 예산 여유가 바닥이고, 한도·허용치를 여유와 비교하지 않는다 | 예산을 직전 측정값으로 올려 증가를 묻는 신호가 사라진다. 대조 허용치가 남은 여유보다 크다 | 0929/05-04, 1103/15-04, 1105/15-02 | 레시피 예산은 측정값 + 3%, 3% 초과는 커밋 본문에 이유(1101 README 14.1절). 06장 5절 | 14, 21, 13 |
| P-47 | 성능 측정이 화면 하나·조건 하나만 본다 | lab이 한 화면, `/`의 CLS, 스크롤바를 숨긴 Chromium만 재고 release 단계에서만 돈다 | 1103/15-01, 1105/15-04, 1105/15-01, 1105/15-05 | 06장 2절·6절 | 14, 21, 13 |
| P-48 | 필요 없는 코드가 초기 청크에 실린다 | 첫 화면에 필요 없는 코드가 배럴·side effect 판정 때문에 초기 청크에 들어간다 | 0925/13-14, 1101/08-08 | design-system side effect 없음 선언, 기능 선언과 실행부 분리(1101 README 14.1절) | 14, 13, 22 |
| P-49 | 작은 변경이 캐시·청크 전체를 다시 받게 한다 | build id 하나, 파일 하나 변경이 큰 청크·캐시 전체를 무효화한다 | 0929/13-03, 1101/06-05 | react-dom 청크 분리(`docs/operations/performance-evidence.md` 「build id와 재방문 캐시」) | 14, 13 |
## 7. 이 목록을 고칠 때
- 리뷰 라운드가 끝나면 새 반복 모양을 행으로 더한다. 한 번만 나온 것은 넣지 않는다.
- 번호는 다시 매기지 않는다. 다른 장이 번호로 가리킨다. 번호 순서와 절 순서가 다른 행(예: 1절의 P-24, 4절의 P-03)은
처음 묶을 때 생긴 것이다. 새 행은 마지막 번호 다음을 쓴다.
- 막는 기준이 생기면 그 기준은 해당 장(04·05·06·07)에 쓰고 이 표는 그 장을 가리킨다.
## 지금 이해하면 되는 것
- 결함은 같은 모양으로 돌아온다. 리뷰 전에 이 표를 훑는다.
- 가장 많이 돌아온 것은 게이트가 틀린 답을 내는 모양(P-01·02·05·07·09·12)과 판정 규칙의 빈틈(P-13·28·29)이다.
- 「막는 기준: 없음」인 행이 다음 개선 후보다.