diff --git a/CLAUDE.md b/CLAUDE.md index 6c9a9ac2..79ebac65 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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/-maturity-review/NN-<영역>.md`에 결과를 쓴다. 5. 오케스트레이터는 High 이상 발견을 코드에서 직접 재확인한 뒤 같은 폴더의 `README.md`에 범위(36.1), 28개 관점 판정표(36.2), 최종 요약(36.5), 발견 색인을 쓴다. diff --git a/docs/README.md b/docs/README.md index 6435d08c..a87de3f7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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). 같은 문서의 나머지 절은 목표 설계다 diff --git a/docs/improvement/01-procedures.md b/docs/improvement/01-procedures.md new file mode 100644 index 00000000..e9fa8e3b --- /dev/null +++ b/docs/improvement/01-procedures.md @@ -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, 또는 커밋 범위(`..`). +- 기준 커밋과 지난 라운드의 결정·남은 문제를 읽었다. + +**단계** + +전체 리뷰의 뼈대는 `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/-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(): ...` 커밋. 본문에 보존 조건과 버린 대안(커밋 규칙 3.3절). + +**완료 기준** + +- 테스트 변경 없이 빠른 게이트 8개가 통과한다. +- 줄어든 이해 비용을 한 문장으로 말할 수 있다(읽을 파일 수, 알아야 할 규약 수 등). + +## 4. 성능 최적화 + +**시작 조건** + +- 같은 조건에서 두 번 이상 잰 숫자가 있고, 예산을 넘거나 회귀했다(06장 2절). +- 그 숫자를 만든 측정 조건(위치·부하·반복 수·빌드)을 안다. + +**단계** + +1. 기준선을 06장 3절 조건으로 다시 잰다. 예전 측정값을 기준선으로 쓰지 않는다. +2. 원인을 좁힌다. 무엇이 비용을 만드는지 네트워크 waterfall·청크 목록·trace로 확인한다. +3. 바꾼다. 초기 JS 예산·초기 파일 수 상한·lab 예산을 함께 본다. 하나를 줄이며 다른 하나를 넘기지 않는다(06장 4절). +4. 같은 조건으로 다시 잰다. 대조군(바꾸기 전 커밋)을 같은 세션에서 함께 잰다. +5. 기준선 파일을 고쳐야 하면 06장 5절 절차를 따른다. + +**산출물** + +- 전후 숫자와 측정 조건(06장 3절 항목 전부). `perf(): ...` 커밋. + +**완료 기준** + +- `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(): ...` 또는 `fix(test): ...` 커밋. 본문에 원인, 결정적 재현 방법, 반복 실행 결과. + +**완료 기준** + +- 변이 또는 결정적 재현이 고친 뒤 기대대로 실패·통과한다. +- 반복 실행에서 실패 0이다. 횟수를 적는다(1103/11-10은 고친 뒤 30회 반복, 660/660 통과). + +## 지금 이해하면 되는 것 + +- 작업 종류는 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"로 고른다. +- 결함 수정은 RED 먼저, 발견 ID와 함께, 템플릿 원래 상태 밖에서도 확인한다. +- 리뷰는 코드를 고치지 않고, 게이트는 한 번 돌려 모두가 함께 읽는다. diff --git a/docs/improvement/02-review-criteria.md b/docs/improvement/02-review-criteria.md new file mode 100644 index 00000000..58c45bdc --- /dev/null +++ b/docs/improvement/02-review-criteria.md @@ -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/-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이다. +- 증거는 현재 커밋의 실행에서, 조건을 붙여서. 지난 「고침」도 다시 본다. diff --git a/docs/improvement/03-folder-module-structure.md b/docs/improvement/03-folder-module-structure.md new file mode 100644 index 00000000..13caa63a --- /dev/null +++ b/docs/improvement/03-folder-module-structure.md @@ -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// ── 지울 수 있는 기능 하나 (제거 드릴, 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//`와 `tests/features//`. 기능끼리, 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를 같은 커밋에서 고치고 제거 드릴을 돌린다. diff --git a/docs/improvement/04-code-structure.md b/docs/improvement/04-code-structure.md new file mode 100644 index 00000000..441701f6 --- /dev/null +++ b/docs/improvement/04-code-structure.md @@ -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 + +## 지금 이해하면 되는 것 + +- 판정 규칙은 한 곳, 표 밖은 안전한 쪽. 결과 불명 쓰기의 모든 재전송 입구를 함께 본다. +- 같은 사실은 원본에서 뽑거나 대조 테스트로 묶는다. 짝 백엔드 사실은 코드까지 따라간다. +- 수정은 새로 가정하는 것을 적고, 그 가정이 깨지는 구성에서 돌려 본다. diff --git a/docs/improvement/05-test-structure.md b/docs/improvement/05-test-structure.md new file mode 100644 index 00000000..877dcc50 --- /dev/null +++ b/docs/improvement/05-test-structure.md @@ -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//` | 기능 폴더와 함께 지워진다 | + +- 스크립트 테스트가 자식 프로세스를 띄우면 그 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으로 덮지 않는다. 반복 실행 → 실패 기록 → 결정적 재현 → 수정 → 변이 순서로 + 원인을 찾는다. diff --git a/docs/improvement/06-performance.md b/docs/improvement/06-performance.md new file mode 100644 index 00000000..65ac3320 --- /dev/null +++ b/docs/improvement/06-performance.md @@ -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 게이트도 돌린다. +- 측정값에는 위치·부하·반복 수·빌드·대조군을 붙인다. 붙이지 않은 숫자는 비교하지 않는다. diff --git a/docs/improvement/07-verification-gates.md b/docs/improvement/07-verification-gates.md new file mode 100644 index 00000000..f5243951 --- /dev/null +++ b/docs/improvement/07-verification-gates.md @@ -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