커밋 전 검사 8개, 통합 때 5개, 옛 게이트 11개처럼 config/ci/gates.json과 표가 정하는 개수를 문장에 옮겨 적었다. 표가 바뀌면 문장이 낡는다(문서 체계 검사의 숫자 복사 규칙). 개수를 빼고 표를 가리킨다. 검증: scripts/verify.sh docs rc=0.
151 lines
17 KiB
Markdown
151 lines
17 KiB
Markdown
# 개선 — 리뷰, 결함 수정, 리팩터링, 성능, 구조, 테스트 구조
|
|
|
|
이미 있는 코드를 평가하거나 고치는 일의 절차다. 핵심은 하나다: 리뷰 → 수정 → 다음 라운드 리뷰를 새 High 0·새 P1 0·merge 게이트 전부 통과까지 돌고, 그 라운드의 Medium·Low를 고친 뒤 멈춘다(4.5절).
|
|
|
|
## 1. 언제 쓰나
|
|
|
|
| 지금 상태 | 작업 |
|
|
| --- | --- |
|
|
| 무엇이 틀렸는지 아직 모른다 | 리뷰 |
|
|
| 계약(지원 범위, 현재 계약 문서, 게이트, 생성 명령, 짝 계약)과 다른 동작이 확인됐다 | 결함 수정 |
|
|
| 동작은 맞는데 구조 비용이 크다 | 리팩터링 |
|
|
| 같은 조건에서 두 번 이상 잰 숫자가 예산을 넘거나 회귀했다 | 성능 최적화 |
|
|
| 최상위 `src/` 폴더, adapter 그룹, 기능·context 경계, import 규칙이 바뀐다 | 구조 변경 |
|
|
| 테스트가 주장을 증명하지 못하거나 가끔 떨어진다 | 테스트 구조 개선 |
|
|
|
|
- 새 기능은 [new-feature.md](new-feature.md)다. 고치기 전에 소유자 결정이 필요하면 [research-design.md](research-design.md)가 먼저다.
|
|
|
|
## 2. 받아야 할 것
|
|
|
|
- 리뷰: 범위(전체 / 영역 / PR / 커밋 범위 `<base>..<head>`), 기준 커밋.
|
|
- 수정: 고칠 발견 목록(ID, 위치)과 리뷰 문서 경로. 발견 ID 없이 고치지 않는다. 그 고침이 무엇을 막는지 아무도 모르게 된다.
|
|
- 공통: 브랜치, 커밋 허용 여부, 돌릴 게이트. 그 발견에 필요한 소유자 결정이 [reference/decisions.md](reference/decisions.md)에도 brief에도 없으면 그 발견만 멈추고 묻는다.
|
|
|
|
## 3. 크기와 사고 순서
|
|
|
|
- 보통 중간이다: 영역 리뷰 하나, 수정 묶음 하나. 큼: 전체 리뷰, 구조 변경, 공개 포트·계약을 바꾸는 수정. 큰 일은 설계와 대안을 먼저 적는다(리뷰 가이드 41절의 일곱 질문).
|
|
- 선행 사례는 둘이다: 같은 원인이 남은 다른 자리, 그리고 [reference/defect-patterns.md](reference/defect-patterns.md)의 같은 모양. 리뷰 전에 그 표를 훑는다.
|
|
- 스킬은 소유자 규칙이다(리뷰·수정에 스킬을 쓴다). 불렀다는 사실보다 그 스킬의 기준으로 무엇을 봤는지가 증거다.
|
|
|
|
| 작업 | 절차 스킬 | 영역 스킬(바뀌는 경계에 맞춰) |
|
|
| --- | --- | --- |
|
|
| 리뷰 | `superpowers:requesting-code-review` | `clean-architecture`, `codebase-design`, `security-and-hardening`, `performance-optimization`, `playwright-best-practices`, `frontend-ui-engineering`, `doubt-driven-development` |
|
|
| 리뷰 결과를 받아 고칠 때 | `superpowers:receiving-code-review` | — |
|
|
| 결함 수정 | `superpowers:systematic-debugging` → `superpowers:test-driven-development` | 바뀌는 경계의 영역 스킬 |
|
|
| 리팩터링 | `refactor`, `codebase-design` | `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` |
|
|
|
|
## 4. 절차
|
|
|
|
### 4.1 리뷰
|
|
|
|
1. 범위를 고정한다: 기준 커밋, 브랜치, 확인 시점, 노트북 worktree와 desktop이 깨끗한지. 전체 리뷰면 리뷰 가이드 0.1절 전제 표를 채운다. 이 repo의 고정 전제는 루트 `AGENTS.md` 첫 문단과 꼭 지킬 것 1·2다. 요청량·데이터량 목표가 없으니 그 칸은 "기능 수 증가 축과 번들·lab 예산으로 판정"으로 적는다.
|
|
2. 게이트를 한 번 돌린다: `VERIFY_SNAPSHOT=1 scripts/verify.sh merge`와 `scripts/verify.sh documentation`. 손으로 적은 명령 목록을 돌리지 않는다(merge 게이트 일부가 빠진 사건이 있다).
|
|
3. 결과를 함께 읽는다. desktop 로그 폴더(`/tmp/claude-gates/<로그 이름>/`)의 게이트 로그와 `snapshot/`(artifacts·dist·test-results 사본)을 모든 리뷰어가 읽는다. 리뷰어마다 다시 돌리지 않는다([delegate.md](delegate.md) 4.2절).
|
|
4. 영역을 나눈다. 가장 최근 `docs/reviews/*-maturity-review/README.md`의 영역 표를 다시 쓴다. 영역마다 서브에이전트 하나(결과만 받음) 또는 하위 세션 하나(문서를 커밋함).
|
|
5. 영역 문서는 「지난 발견 재판정」부터 쓴다. 지난 라운드가 "고침"이라 한 것도 코드로 다시 본다. 코드는 들어왔지만 완료 기준 실행이 없으면 "일부"다.
|
|
6. 더 필요한 실험은 목록으로 낸다(ID, 명령, env, 시간 상한, 변이 패치). 총괄이 모아 같은 명령은 한 번만, 실험마다 작업 폴더를 되돌리며 일괄로 돌린다.
|
|
7. 발견을 [reference/review-criteria.md](reference/review-criteria.md) 양식으로 적는다. 같은 결함을 두 영역이 적으면 색인에서 하나로 합치고 「합친 중복」 표에 남긴다.
|
|
8. 총괄이 High 이상과 새 P1을 코드에서 직접 다시 읽거나 실행해 확인하고, 재확인 칸에 그 사실을 적는다.
|
|
9. README에 범위, 28개 관점 판정표, 최종 요약, 발견 색인을 쓴다(양식 review-criteria.md 7절). 총괄 자신의 실수도 적는다.
|
|
|
|
- PR·diff 리뷰는 바뀐 파일의 영역만 읽는다. 게이트는 2단계대로 한 번 돌린다(멈춤 판정에 merge 단계 전부가 필요하다). 범위의 base는 직전 리뷰(diff 리뷰 포함)가 본 범위의 끝 커밋, head는 맡긴 쪽이 정한 커밋(없으면 fetch한 `origin/main`)이고 둘을 머리말에 적는다. 판정 체계·양식·ID 체계(`NN-MM`)는 같고, 수정 라운드의 diff 리뷰는 그 라운드 README 「조치」 절 아래 절로 적는다.
|
|
- 리뷰 중에 코드를 고치지 않는다. 의심 결함은 별도 worktree의 임시 테스트로 확인하고 그 코드는 리뷰 문서나 공유 노트에만 남긴다. 리뷰 문서는 리뷰 시점 기록이다. 고친 뒤에도 영역 문서를 고치지 않고, 처리 결과는 같은 README의 「조치」 절에 적는다.
|
|
|
|
### 4.2 결함 수정
|
|
|
|
1. 원인 경로를 확인한다. 증상이 아니라 원인을 적는다. 발견의 「완료 기준」 칸을 읽는다. 완료 기준의 기준은 그 칸이다.
|
|
2. RED: 재현 테스트를 먼저 쓰고 수정 전 코드에서 실패하는 것을 실행으로 본다. 브라우저 없이 재현할 수 없으면 fake·fixture로 조건을 만든다. 리뷰가 Playwright 검증을 요구하면 spec 하나를 더한다.
|
|
- RED가 없는 수정: 문서를 동작에 맞추면 문서의 주장을 단언하는 임시 테스트가 기준 커밋에서 실패하는 것을 RED로 쓴다. 테스트로 옮길 수 없으면 "RED 없음 — 이유"와 대신한 증거를 적는다.
|
|
3. 검출력이 문제였던 발견(변이 생존)은 리뷰에 적힌 변이를 다시 넣어 새 테스트가 실패하는지 본다([reference/testing.md](reference/testing.md) 3절).
|
|
4. GREEN: 가장 작은 수정으로 통과를 본다. 공개 포트는 추가만 한다. 공용 로직은 `src/adapters/platform/`이나 `src/contracts/`에 둔다.
|
|
5. 같은 원인의 다른 자리를 찾는다. 결과 불명 쓰기의 재전송 입구처럼 하나를 막으면 다른 입구에서 다시 나온다([reference/structure.md](reference/structure.md) 6절).
|
|
6. 템플릿 원래 상태 밖에서도 돌린다: 기능을 더한 상태(`create:feature`), 제품 확장 지점을 채운 상태, 입력·객체가 셋 이상. 원래 상태로만 확인한 수정이 다음 라운드에 다시 결함이 됐다.
|
|
7. 수정이 새로 가정하는 것을 커밋 본문 「위험·한계」에 적는다(8절 「새로 가정하는 것」).
|
|
8. 그 동작을 설명하는 문서를 같은 변경에서 고친다. adapter 파일을 더하거나 옮기면 `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다. 다운스트림에 보이는 변경은 `CHANGELOG.md` 미출시 절에 적는다.
|
|
9. 커밋 전 게이트를 돌린다([reference/gates.md](reference/gates.md) 2절).
|
|
|
|
### 4.3 리팩터링, 성능, 구조, 테스트 구조
|
|
|
|
- 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 먼저 적는다(리뷰 가이드 36.3·39.9절). 기존 테스트가 그 조건을 지키는지 보고, 못 지키면 테스트부터 더한다. 바꾼 뒤 같은 테스트가 그대로 통과해야 한다. 테스트를 고쳐야 통과하면 동작이 바뀐 것이다. 소비자 없는 확장 지점은 지우지 않고, 갈라진 복사본은 하나로 합친다.
|
|
- 성능: [reference/performance.md](reference/performance.md)의 조건으로 기준선을 다시 잰다 → 원인을 좁힌다(waterfall·청크 목록·trace) → 변경 하나 → 대조군(바꾸기 전 커밋)과 같은 세션에서 다시 잰다. 지난 측정값을 기준선으로 쓰지 않는다.
|
|
- 구조 변경: 설계와 대안을 먼저 적고, [reference/structure.md](reference/structure.md) 3절 「바꿀 때 같이 고칠 것」을 같은 커밋에서 고친 뒤 제거 드릴(FE-GATE-020)을 돌린다.
|
|
- 테스트 구조: [reference/testing.md](reference/testing.md). 가끔 떨어지는 테스트는 재시도·timeout으로 덮지 않고 반복 실행 → 실패 기록 → 결정적 재현 → 수정 → 변이 순서로 원인을 찾는다.
|
|
|
|
### 4.4 수정 라운드와 묶음
|
|
|
|
- 통합 브랜치 `fix/maturity-review-<YYYY-MM-DD>`(리뷰 날짜)를 만들고, 영역별 수정은 각자 worktree의 브랜치에서 한다. 다른 수정에 기대는 묶음은 그 수정이 합쳐진 뒤 시작한다. CHANGELOG·문서는 마지막에 한 세션이 다시 쓴다.
|
|
- 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 커밋 전 게이트를 돌린다. 합친 뒤에만 생긴 실패는 README 「통합에서 생긴 것」에 적는다. 합친 트리에서 merge 단계를 돌리고 회차별 결과를 표로 남긴다.
|
|
- 큰 라운드는 작은 PR로 나눈다. 자기완결적인 변경 하나에 PR 하나(대략 100줄, 1,000줄이면 너무 크다). 리팩터링과 동작 변경은 PR을 나눈다. 병합은 소유자가 한다. 라운드 사이에 새 기능이나 큰 구조 변경을 넣지 않는다(발견 수가 줄어드는지 볼 수 없다).
|
|
|
|
### 4.5 멈춤 기준 — 이 repo는 하나다
|
|
|
|
아래 셋을 모두 채운 라운드에서 멈춘다(소유자 결정 2026-11-04).
|
|
|
|
1. 그 라운드의 새 High 0.
|
|
2. 그 라운드의 새 P1 0.
|
|
3. merge 단계 게이트 전부 통과([reference/gates.md](reference/gates.md) 3절 방법). FE-GATE-013을 어떻게 셀지는 결정 대기라, 그동안은 같은 절의 문구로 보고하고 멈출지는 소유자가 정한다.
|
|
|
|
- 채워도 바로 끝내지 않는다. 그 라운드의 Medium·Low를 고치고 멈춘다. 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 남긴다(형식 [reference/decisions.md](reference/decisions.md) 3절). 이유 없는 이월("나중에", "범위 밖")은 남기지 않는다.
|
|
- 마지막 Medium·Low 수정은 다음 리뷰를 받지 않는다. 그래서 그 수정도 4.2절 6단계와 merge 판정을 그대로 거친다. 짝 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 두 기준을 맞추지 않는다(소유자 결정 2026-11-05 「각자 유지」).
|
|
- 2026-11-03 리뷰의 수정 라운드 뒤로 세 라운드를 더 돌아도 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게 보고한다. 라운드는 전체 리뷰 한 번이다(diff 리뷰는 세지 않는다). 2026-11-05·06 리뷰가 그 첫째·둘째다.
|
|
- 수정 결과의 "고침"은 확정이 아니다. 다음 리뷰가 ID별로 다시 판정한다. 보고에도 "다음 리뷰에서 재판정"이라고 적는다.
|
|
|
|
## 5. 완료 기준
|
|
|
|
- 리뷰: 모든 발견이 양식이고 성격·심각도·우선순위·통제·증거가 따로 있다. 지난 발견 전부의 지금 상태가 표 하나에 있다. 미검증 목록과 확인 방법, 결정이 필요한 항목마다 선택지와 결정할 사람이 있다.
|
|
- 결함 수정(모든 발견에 공통):
|
|
1. 동작을 바꾸면 RED → GREEN이 실행으로 있다. 없으면 "RED 없음 — 이유"와 대신한 증거가 있다.
|
|
2. 검출력이 문제였던 발견은 변이를 다시 넣어 새 테스트가 실패한다.
|
|
3. 커밋 전 검사(package script)가 통과한다: `check:architecture`, `check:types`, `lint`, `test:unit`, `test:component`, `test:integration`, `test:contract`, `test:runtime-schema`.
|
|
4. 묶음 끝과 통합 때는 더해서 `check:ci`, `check:adapter-inventory`, `verify:documentation`, `test:sample-removal`, `build`가 통과한다.
|
|
5. adapter 파일을 더하거나 옮겼으면 INVENTORY를 같은 커밋에서 고쳤다.
|
|
6. 공용 로직은 kernel이나 `src/contracts/`에 있고 새 파일 단위 예외가 없다.
|
|
7. 공개 포트는 추가만 했다. 깼으면 결정 표와 BREAKING 커밋이 있다.
|
|
8. 논리 변경 하나에 커밋 하나, 메시지에 발견 ID, 바꾼 파일만 stage했다.
|
|
9. 문서 요구는 문서의 각 주장이 코드 위치를 가리키는 것으로 확인했다.
|
|
- 발견별 상태가 「고침 / 일부 / 결정 대기」 중 하나이고, 리뷰 가이드 35.6절의 다섯 연결(원래 위험, 바꾼 코드, 그 위험을 잡는 검증, 검증한 버전·환경·결과, 남은 제한)이 있다.
|
|
- 리팩터링: 테스트 변경 없이 커밋 전 검사가 통과한다. 줄어든 이해 비용을 한 문장으로 말할 수 있다.
|
|
- 성능: `check:bundle`(FE-GATE-012)과 `test:performance`(FE-GATE-026)가 통과하고, 전후 차이가 측정 잡음보다 크다(잡음 크기를 함께 적는다).
|
|
- 구조 변경: `check:architecture`, `check:adapter-inventory`, `verify:documentation`, FE-GATE-020이 통과한다. merge 가능을 말하려면 merge 단계 전부가 통과했다.
|
|
- 테스트 구조: 변이나 결정적 재현이 고친 뒤 기대대로 실패·통과하고, 반복 실행 실패 0과 횟수가 있다.
|
|
|
|
## 6. 하지 말 것
|
|
|
|
- 리뷰 중에 코드를 고치지 않는다.
|
|
- 지난 라운드의 실행 결과나 다른 세션이 낸 "통과"를 현재 증거로 쓰지 않는다. 바뀐 커밋에서 다시 돌린다.
|
|
- 정한 결정을 결함으로 다시 올리지 않는다. 전제가 틀렸다는 새 증거가 있을 때만 근거와 함께 다시 연다.
|
|
- 범위 밖 결함을 고치지 않는다. 버리지도 않는다. 보고의 「범위 밖에서 본 것」에 위치와 함께 적는다. 같은 결함을 여러 번 세지 않는다.
|
|
- 게이트 기준(문턱, 예산, 기준선, skip·only)을 낮춰 통과시키지 않는다. 문서 검사를 피하려고 경로를 백틱 밖으로 옮기지 않는다.
|
|
- 짝 백엔드 repo에 쓰지 않는다. 백엔드가 바꿔야 할 것은 "백엔드에 넘길 것"으로 적는다.
|
|
|
|
## 7. 막혔을 때
|
|
|
|
- 고치는 법이 공개 동작(배럴 표면, 런타임 설정 키, 짝 계약, 파생 프로젝트 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 [README](README.md) 5절이다.
|
|
- RED를 만들 수 없으면(실제 브라우저·호스트 권한이 필요하다, 기계에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다.
|
|
- 같은 파일·장치에서 결함이 두 라운드 연속 나오면, 다음은 수정이 아니라 [research-design.md](research-design.md)로 "이 장치가 필요한가"를 먼저 본다.
|
|
|
|
## 8. 보고 형식
|
|
|
|
[README](README.md) 6절에 더해, 고친 발견마다 아래 칸을 쓴다. 리뷰 README의 「조치」 표에 그대로 옮길 수 있게 쓴다.
|
|
|
|
| 칸 | 적을 것 |
|
|
| --- | --- |
|
|
| 발견 | ID와 한 줄 내용 |
|
|
| 상태 | 고침 / 일부(남은 것) / 결정 대기(이유·선택지·결정할 사람) |
|
|
| RED·GREEN | 수정 전 실패한 테스트와 수정 뒤 통과, 로그 경로. 없으면 "RED 없음 — 이유" |
|
|
| 검증 | 명령, 테스트 수, rc, 실행 위치(desktop), env(CI env인지), 로그 경로 |
|
|
| 새로 가정하는 것 | 빈 제품 파일, CI env 없음, 객체 하나, 기능 0개처럼 이 변경이 새로 기대는 상태와, 그 가정이 깨지는 구성에서 돌렸는지 |
|
|
| 약해진 검사 | 이 변경이 다른 검사를 약하게 했는가(없으면 없음) |
|
|
| 범위 밖에서 본 것 | 위치와 내용. 고치지 않았다 |
|
|
|
|
## 9. 자주 하는 실수
|
|
|
|
- 게이트 목록을 지난 라운드에서 가져온다. `scripts/verify.sh merge`로 stage 전부를 돌린다.
|
|
- 다시 돌려 통과한 결과를 "통과"로 쓴다. 실패한 회차를 적고 원인을 찾는다.
|
|
- 지운 코드의 실행 동작만 옮기고, 그 코드를 읽던 검사·테스트가 지키던 것을 놓친다. 지우기 전에 `git grep`으로 읽는 곳을 찾는다.
|
|
- 짝 백엔드 사실을 문서만 보고 옮긴다. 생성기와 폼까지 코드를 따라간다.
|
|
- "부하 탓"으로 닫는다. 부하를 낮춘 재현과 결정적 재현으로 확인하기 전에는 원인이 아니다.
|