docs(improvement): 리뷰·수정·리팩터링의 기준이 되는 개선 작업 매뉴얼을 둔다 #6
@@ -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), 발견 색인을 쓴다.
|
||||
|
||||
@@ -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). 같은 문서의 나머지 절은 목표 설계다
|
||||
|
||||
@@ -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와 함께, 템플릿 원래 상태 밖에서도 확인한다.
|
||||
- 리뷰는 코드를 고치지 않고, 게이트는 한 번 돌려 모두가 함께 읽는다.
|
||||
@@ -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를 같은 커밋에서 고치고 제거 드릴을 돌린다.
|
||||
@@ -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
|
||||
|
||||
## 지금 이해하면 되는 것
|
||||
|
||||
- 판정 규칙은 한 곳, 표 밖은 안전한 쪽. 결과 불명 쓰기의 모든 재전송 입구를 함께 본다.
|
||||
- 같은 사실은 원본에서 뽑거나 대조 테스트로 묶는다. 짝 백엔드 사실은 코드까지 따라간다.
|
||||
- 수정은 새로 가정하는 것을 적고, 그 가정이 깨지는 구성에서 돌려 본다.
|
||||
@@ -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으로 덮지 않는다. 반복 실행 → 실패 기록 → 결정적 재현 → 수정 → 변이 순서로
|
||||
원인을 찾는다.
|
||||
@@ -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 게이트도 돌린다.
|
||||
- 측정값에는 위치·부하·반복 수·빌드·대조군을 붙인다. 붙이지 않은 숫자는 비교하지 않는다.
|
||||
@@ -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을 되돌린다.
|
||||
@@ -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 꼬리말은 없다.
|
||||
@@ -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를 고치고 멈춘다. 못 고친 것은 결정 대기로 남긴다.
|
||||
@@ -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)이다.
|
||||
- 「막는 기준: 없음」인 행이 다음 개선 후보다.
|
||||
Reference in New Issue
Block a user