문제: 2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을
시켰다. 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 세션마다
1~9건 나왔고, 세 곳은 문서끼리 다르게 말했다.
- 리뷰 README를 누가 쓰나: delegate.md는 총괄, improve.md는 리뷰어
- push: README 4절·decisions.md는 "커밋을 허용하면 push도", 정본
delegation-loop.md 11절은 brief가 push를 따로 허용해야 한다
- evidence.md 머리말은 "RR-는 1차 재리뷰"라는데 round2도 RR-를 썼다
고른 방법:
- 리뷰어는 README에 자기 라운드 색인 절 하나만 쓰고, 처리 표·결정의
답·게이트 기록은 총괄이 쓴다(improve.md 4.1, delegate.md 4.2,
decisions.md 2.1)
- 커밋과 push는 brief 7절이 따로 허용한다. 커밋만 허용되면 push하지
않는다. push 없이도 패치와 트리 해시로 desktop에서 검증한다
(operate.md 4.1 「push 전에 검증하기」). 이 방법은 커밋 본문에
desktop 결과를 넣으려는 세션의 빈틈도 닫는다
- evidence.md 머리말을 접두어별 문서로 고친다
- 나머지 빈틈은 그 일을 하는 playbook의 절차 단계나 자주 하는 실수,
reference에 한 줄씩 넣는다. 36행 처리 표는 evidence.md 9절이다
(고침 35, 고치지 않음 1: 새 매뉴얼에 이미 답이 있던 것)
버린 대안: push를 "커밋 허용이면 push도"로 읽기. 정본 11절과 실제
brief(백엔드는 push, design-docs는 push 안 함)가 push를 따로 다룬다.
버린 대안: 빈틈을 모두 자주 하는 실수에 넣기. 10줄 상한을 넘고, 절차의
한 단계인 것은 그 단계에 있어야 읽힌다.
위험·한계:
- 리뷰 README 분담, push를 따로 읽는 것, 하위 세션 Slack은 기본값이다.
소유자가 뒤집을 수 있게 decisions.md에 기본값으로 적었다
- AGENTS.md의 커밋 예외 문장은 이번 범위 밖이라 그대로다. 세부는 이
README 4절을 가리키므로 README가 정한다
- 고친 매뉴얼은 2회차 cold-read 시험 전이다
검증:
- python3 scripts/check-work-docs.py rc=0. 지도 73/120, README 76/80,
improve.md 134/150, 진입 경로 최대 283/350, 본문 이력 0줄
- python3 scripts/check-work-docs.py --links docs CLAUDE.md 결과 링크
432개, 깨진 것 0
- desktop: 바꾼 것을 패치로 기준 커밋 2c8a359d 위에 얹어 노트북과 같은
트리 3d0e5900을 만들고 flock 아래
:app-bootstrap:documentContractTest --rerun rc=0, 66건 실패 0
건너뜀 0, 13초, 직전 1분 부하 3.13
(desktop ~/manual-gap-fix-1-logs/documentContractTest.log)
135 lines
14 KiB
Markdown
135 lines
14 KiB
Markdown
# 개선 — 리뷰, 결함 수정, 리팩터링, 성능, 구조, 테스트 구조
|
|
|
|
이미 있는 코드를 평가하거나 고치는 일의 절차다. 핵심은 하나다: 리뷰 → 수정 → 확인 리뷰를 발견이 0이 될 때까지 돈다.
|
|
|
|
## 1. 언제 쓰나
|
|
|
|
| 지금 상태 | 작업 |
|
|
| --- | --- |
|
|
| 무엇이 틀렸는지 아직 모른다 | 리뷰 |
|
|
| 계약(이름·Javadoc·문서·레지스트리·테스트 이름이 약속한 것)과 다른 동작이 확인됐다 | 결함 수정 |
|
|
| 동작은 맞는데 구조 비용이 크다 | 리팩터링 |
|
|
| 숫자로 잰 비용이 크다 | 성능 최적화 |
|
|
| leaf·패키지·허용 의존이 바뀐다 | 구조 변경 |
|
|
| 테스트가 이름이 말한 것을 증명하지 못한다 | 테스트 구조 개선 |
|
|
|
|
- 새 업무 기능은 [new-feature.md](new-feature.md)다.
|
|
- 고치기 전에 소유자 결정이 필요하면 [research-design.md](research-design.md)가 먼저다.
|
|
|
|
## 2. 받아야 할 것
|
|
|
|
- 리뷰: 범위(전체 / 영역 / 커밋 범위 `<base>..<head>`와 pathspec), 쓸 심각도 체계(전체 리뷰용인지 확인 리뷰용인지).
|
|
- 수정: 고칠 발견 목록(ID, 위치)과 리뷰 문서 경로.
|
|
- 공통: 기준 커밋, 브랜치, 커밋 허용 여부, 검증할 게이트.
|
|
- 그 발견에 필요한 소유자 결정이 났는지. [reference/decisions.md](reference/decisions.md)에 없고 brief에도 없으면 그 발견만 멈추고 묻는다.
|
|
|
|
## 3. 크기와 사고 순서
|
|
|
|
- 보통 중간이다: 확인 리뷰 하나, 수정 묶음 하나.
|
|
- 큼: 전체 리뷰, 구조 변경, 공개 계약을 바꾸는 수정. 큰 일은 1~5단계 결과와 대안을 소유자가 먼저 본다.
|
|
- 이 작업에서 선행 사례는 둘이다: 같은 원인이 남은 다른 자리, 그리고 [reference/defect-patterns.md](reference/defect-patterns.md)의 같은 모양.
|
|
- 대안은 고치는 법 2~3개를 비교한다. 고른 것과 버린 것을 커밋 본문에 쓴다.
|
|
- 스킬: 리뷰는 `superpowers:requesting-code-review`의 리뷰어 지침과 바뀐 경계의 영역 스킬, 결함 수정은 `superpowers:systematic-debugging` → `superpowers:test-driven-development`, 리팩터링은 `refactor`·`codebase-design`, 성능은 `performance-optimization`, 구조 변경은 `superpowers:brainstorming` → `superpowers:writing-plans`. 리뷰 결과를 받아 고칠 때는 `superpowers:receiving-code-review`.
|
|
- 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 이 세션이 직접 한다. 나눠야 하면 [delegate.md](delegate.md)대로 별도 세션에 맡긴다.
|
|
|
|
## 4. 절차
|
|
|
|
### 4.1 리뷰
|
|
|
|
1. 범위를 고정한다. 확인 리뷰는 pathspec과 `git diff --stat <base>..<head> -- <pathspec>` 결과를 문서에 적는다.
|
|
2. 확인 리뷰는 수정 보고의 「새로 가정하는 것」 칸부터 본다. 가정마다 다른 코드·설정·운영에서 참인지 확인한다. 그 칸이 없으면(보고가 repo에 없거나 옛 양식) 수정 커밋 본문의 「위험·한계」와 리뷰 README 처리 표의 「결정」 칸에서 가정을 뽑고, 뽑은 곳을 문서 「범위」 절에 적는다.
|
|
3. 그다음 수정 diff와, diff가 바꾼 동작의 주변 코드를 읽는다. 확인 리뷰는 저장소 전체가 아니라 그 수정만 본다. 읽은 주변 코드에서 본 결함은 이전부터 있었어도 발견으로 적고 「이전부터」로 표시한다. 그 밖을 찾아 나서지 않는다.
|
|
4. 전체 리뷰는 게이트를 먼저 한 번 돌려 결과를 적고([reference/gates.md](reference/gates.md)), 영역을 나눈다([delegate.md](delegate.md) 「나누는 법」).
|
|
5. 의심 결함은 별도 worktree의 임시 테스트(탐침)로 확인한다. 탐침 코드는 고칠 때 옮겨 쓸 수 있게 남기고(소유자 환경에서는 공유 노트 폴더, design-docs `conventions/delegation-loop.md` 11절), worktree는 지운다.
|
|
6. 발견을 [reference/review-criteria.md](reference/review-criteria.md) 양식으로 적는다. 발견마다 증거 수준과 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다.
|
|
7. 리뷰 폴더 README에 이번 라운드의 색인 절 하나를 더한다: 발견 ID, 심각도, 한 줄 내용, 결정이 필요한 질문. 발견 ID를 모두 이름으로 적는다. 범위(`A~B`)와 이어 쓰기(`A·07`)는 된다. 건수만 쓰지 않는다. README의 다른 절(처리 표, 결정의 답, 라운드 끝 게이트)은 맡긴 쪽이 쓴다. 한 라운드를 여러 리뷰 세션이 나눠 보면 색인 절도 맡긴 쪽이 쓰고, 리뷰어는 보고에 같은 표를 둔다.
|
|
8. `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다. 색인 절이 따로 있으면 `--index-heading "<절 제목>"`을 붙인다. rc=0이어야 한다. 지난 라운드 색인에서 빠진 ID 때문에 처음부터 rc=1이면, 빠진 ID를 이번 색인 절에 「색인 보완」 한 줄로 이름만 적는다. 지난 영역 문서는 고치지 않는다.
|
|
9. 판단하지 않은 항목은 「Declined to judge」에 위치와 이유를 적는다. 맡긴 쪽이 다음 묶음에 배정하거나 결정으로 닫는다. 지난 라운드에서 열린 채 넘어온 Declined는 brief가 맡겼을 때만 다시 판정한다. 맡기지 않았으면 건수와 위치만 적는다.
|
|
|
|
### 4.2 결함 수정
|
|
|
|
1. 원인 경로를 확인한다. 증상이 아니라 원인을 적는다.
|
|
2. RED: 결함을 재현하는 테스트를 먼저 쓰고, 수정 전 코드에서 실패하는 것을 실행으로 본다. 실패 메시지가 그 결함을 말해야 한다. 컴파일 오류나 준비 실패는 RED가 아니다.
|
|
3. 수정과 테스트를 이미 같이 썼으면, 기준 커밋에 테스트만 얹은 임시 worktree에서 RED를 본다. 실 DB·Redis가 필요한 결함은 실 vendor lane에서 본다.
|
|
4. 가장 작은 수정으로 GREEN을 본다.
|
|
5. 같은 원인의 다른 자리를 찾는다. 경계마다 다시 구현된 규칙은 한 곳만 고치면 다른 곳에서 다시 갈라진다.
|
|
6. 그 동작을 설명하는 문서를 같은 변경에서 고친다: `docs/web/http-contract.md`, `docs/registries/`, runbook, `docs/manual/`, leaf README·`CLAUDE.md`, Javadoc. 고친 뒤 옛 표현을 grep으로 찾는다.
|
|
7. 파생 서비스가 따라 고쳐야 하면 `docs/upgrade/`의 안내에 행을 더하고, 커밋 제목에 `!`와 `BREAKING CHANGE:` 꼬리말을 단다.
|
|
8. 영향 leaf의 `check`와 그 코드를 지키는 lane을 돌린다([reference/gates.md](reference/gates.md) 2절, 실행 위치는 [operate.md](operate.md)).
|
|
|
|
### 4.3 리팩터링, 성능, 구조, 테스트 구조
|
|
|
|
- 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 적는다. 그 조건을 지키는 테스트가 지금 통과하는지 먼저 본다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다.
|
|
- 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 `CLAUDE.md`에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다.
|
|
- 성능: 숫자 없이 시작하지 않는다. 기준선 측정 → 원인 좁히기 → 변경 하나 → 같은 조건으로 재측정 → 회귀 테스트로 고정. 조건은 review-criteria.md 「성능 측정」, 지난 기준선은 [evidence.md](evidence.md)다. 지난 숫자는 현재 커밋에서 다시 잰다.
|
|
- 구조 변경: 설계서(`docs/superpowers/specs/`)와 계획서(`docs/superpowers/plans/`)를 먼저 둔다. review-criteria.md 「leaf 변경 체크리스트」를 따른다. ArchUnit 규칙을 바꾸면 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 둘 다 둔다.
|
|
- 테스트 구조: 지금 테스트가 증명하는 것(이름, 단언, skip 수)을 적는다. 고친 뒤 지키려는 production 코드를 일부러 망가뜨려 테스트가 실패하는지(변이) 본다. 옮겼으면 lane별 테스트 수를 전후로 비교한다.
|
|
|
|
### 4.4 수정 묶음의 크기
|
|
|
|
- 묶음 하나는 리뷰 영역 하나 안이고 발견 8건 이하다. 묶음마다 커밋 하나다.
|
|
- 확인 리뷰 하나가 보는 수정 diff는 추가 1,500줄 이하다(`git diff --shortstat <base>..<head>`, 테스트 포함, lockfile·스냅숏 같은 생성 파일과 리뷰 기록 `docs/reviews/**` 제외). 넘으면 확인 리뷰를 나눈다. 묶음 커밋이 따로 있으면 커밋별로, 한 커밋에 여러 영역이 섞였으면 영역 pathspec별로(`git diff --shortstat <base>..<head> -- <pathspec>`) 나눠 각각 상한 안이 되게 한다. 테스트 파일은 그 테스트가 지키는 코드의 영역에 넣는다.
|
|
- 나누는 것은 맡긴 쪽이 brief로 한다. 상한을 넘는 범위를 brief 하나로 받았으면, 한 세션이 나눈 단위를 차례로 보고 단위마다 문서 하나를 쓴다. 그렇게 했다고 보고에 적는다.
|
|
- 왜: 지난 수정 라운드에서 추가 줄이 2,000줄 아래면 다음 확인 리뷰 발견이 9건 이하였고, 5,000줄을 넘으면 19건 이상이었다([evidence.md](evidence.md) 「수정 묶음 크기」). 상한 값은 판단이다. 라운드당 새 결함 수로 다시 맞춘다.
|
|
- 묶음을 합친 트리는 따로 검증한다([reference/gates.md](reference/gates.md) 「라운드 끝」). 두 묶음의 수정은 한 트리에서 처음 만날 때 새 결함을 만든다.
|
|
|
|
### 4.5 멈춤 기준 — 이 repo는 하나다
|
|
|
|
리뷰 → 수정 → 확인 리뷰는 아래 넷이 모두 참일 때만 멈춘다.
|
|
|
|
1. 마지막 확인 리뷰의 발견이 심각도와 상관없이 0이다. Minor도 기록만 하지 않고 고친다.
|
|
2. 열린 「Declined to judge」가 0이다. 다른 브랜치가 처리했지만 아직 합치지 않은 항목은 합친 트리에서 확인할 때까지 열린 것으로 센다.
|
|
3. 합친 트리에서 라운드 끝 게이트가 모두 통과했다.
|
|
4. 리뷰 README의 남은 항목이 0이다. 결정으로 닫은 항목은 결정 위치를 적었다.
|
|
|
|
- 다른 멈춤 기준은 이 repo에서 쓰지 않는다. "새 Important가 0이면 멈춤"과 "Minor는 기록만"은 소유자가 거뒀다. 짝 프론트 repo는 자기 기준을 쓴다(소유자 결정 "각자 유지").
|
|
- 코드로 닫을 수 없는 것은 소유자 결정이 필요한 항목뿐이다. 근거와 권하는 안을 붙여 질문으로 보고하고, 답을 받으면 다시 고친다.
|
|
|
|
## 5. 완료 기준
|
|
|
|
- 리뷰: 모든 발견이 양식대로이고 증거 수준이 있다. 색인 검사가 rc=0이다. 결정이 필요한 항목마다 선택지와 권하는 안이 있다.
|
|
- 결함 수정: 수정 전 실패(RED)와 수정 뒤 통과(GREEN) 로그가 있다. 같은 원인의 다른 자리를 확인했다. 해당 게이트가 rc=0이다(desktop 로그 경로). 보고에 「새로 가정하는 것」이 있다.
|
|
- 리팩터링: 보존 조건 테스트가 전후 모두 통과하고 `architectureCheck`가 통과한다. 지운 코드를 가리키는 문서·주석이 grep으로 0이다.
|
|
- 성능: 전후 숫자가 같은 조건에서 나왔다. 회귀 테스트가 어떤 단계에 속한다(`verifyStrictLaneStages --dry-run` 통과).
|
|
- 구조 변경: `architectureCheck`, `verifyDependencyLocks`, `ci`, `mainCheck`가 통과한다. 문서에 leaf 개수를 적지 않았다.
|
|
- 테스트 구조: 변이가 잡혔다. 새 lane이 단계에 속한다. `testQualityCheck`가 통과한다.
|
|
- `docs/work/`나 루트 `CLAUDE.md`를 고쳤으면 `python3 scripts/check-work-docs.py`가 rc=0이다.
|
|
|
|
## 6. 하지 말 것
|
|
|
|
- 리뷰 중에 코드를 고치지 않는다. 리뷰는 읽기 전용이다.
|
|
- 이전 라운드의 실행 결과나 묶음 보고의 "통과"를 현재 증거로 쓰지 않는다. 바뀐 커밋에서 다시 돌린다.
|
|
- 정한 결정을 결함으로 다시 올리지 않는다. 전제가 틀렸다는 새 증거가 있을 때만 근거와 함께 다시 연다.
|
|
- 범위 밖 결함을 고치지 않는다. 버리지도 않는다. 위치와 함께 「Declined to judge」나 보고의 「범위 밖에서 본 것」에 적는다.
|
|
- 같은 결함을 여러 번 세지 않는다. 두 영역이 같은 결함을 적으면 색인에서 하나로 합친다.
|
|
- 어딘가에 적용된 마이그레이션 파일을 고치지 않는다.
|
|
- 전 leaf의 import를 바꾸는 이동을 다른 묶음과 동시에 하지 않는다. 나머지를 합친 뒤 혼자 마지막에 한다.
|
|
|
|
## 7. 막혔을 때
|
|
|
|
- 고치는 법이 공개 동작(응답 코드, 기동 실패 조건, env 키, 파생 서비스 동작)을 바꾸면 고치기 전에 멈추고 묻는다. 형식은 [README](README.md) 5절이다.
|
|
- RED를 만들 수 없으면(실 vendor가 없다, 머신에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다.
|
|
- 계약을 적은 곳끼리(설계서, 포트 Javadoc, 모듈 README, 테스트) 다르게 말하고 [reference/decisions.md](reference/decisions.md)에 결정이 없으면, 어느 쪽도 고르지 않는다. 양쪽 근거를 표로 붙이고 권하는 안과 함께 묻는다. 그 발견만 멈춘다.
|
|
|
|
## 8. 보고 형식
|
|
|
|
[README](README.md) 6절에 더해, 고친 발견마다 아래 칸을 쓴다. 리뷰 README의 처리 표에 그대로 옮길 수 있게 쓴다.
|
|
|
|
| 칸 | 적을 것 |
|
|
| --- | --- |
|
|
| 발견 | 고친 발견의 ID와 한 줄 내용(brief와 리뷰 문서에서는 ID를 쓴다) |
|
|
| 상태 | 완료 / 부분(무엇이 남았나) / 못 함(이유) |
|
|
| RED | 수정 전 실패한 테스트 이름과 수, 로그 경로 |
|
|
| 검증 | 명령, 테스트 수, rc, 로그 경로 |
|
|
| 처리 내용 | 바꾼 것, 고치다 새로 찾아 고친 것 |
|
|
| 새로 가정하는 것 | 이 변경이 다른 코드·설정·운영에 새로 기대는 것. 확인 리뷰가 여기서 시작한다 |
|
|
| 정한 기본값 | 소유자가 확인할 것 |
|
|
| 범위 밖에서 본 것 | 위치와 내용. 고치지 않았다 |
|
|
|
|
## 9. 자주 하는 실수
|
|
|
|
- 색인을 손으로 옮기다 발견이 빠진다. 색인 검사 스크립트를 돌린다.
|
|
- 보고에 없는 태스크 이름을 적는다. 로그에서 태스크 이름을 grep해 확인한다.
|
|
- 묶음별 검증으로 합친 트리 검증을 대신한다. 라운드 끝 게이트를 따로 돌린다.
|
|
- strict lane에 돌릴 탐침을 새 클래스로 만들어 lane이 고르지 않는다. lane은 `build.gradle`의 `requires`(클래스 이름)나 `tag`로 테스트를 고른다. 탐침은 그 lane이 고르는 기존 클래스에 메서드로 넣는다. 탐침도 `-Werror`로 컴파일되니 경고를 남기지 않는다.
|