문제: CLAUDE.md 전체 리뷰 절차 2단계가 돌릴 명령 11개를 손으로 적는다. 이 목록은 merge 단계 명령 87개 중 10개만 돌리고, merge 게이트 14개 중 7개(001, 008, 009, 011, 012, 013, 020)는 전혀 돌지 않는다. 명령을 직접 부르면 ci:gate가 하는 로그·증거 검사, 음성 fixture의 기대 실패, workflow env도 빠진다. 2026-11-03 리뷰가 실제 CI에서 항상 실패하던 merge 게이트 둘(1103/11-06, 12-09)을 놓친 경로다. 고른 방법: 2단계를 "config/ci/gates.json의 merge 단계 gateIds 전부를 workflow env로 ci:gate 하나씩, verify:documentation은 따로"로 바꾸고 목록을 손으로 적지 않는다. 자세한 방법은 개선 매뉴얼 07장 3절을 가리킨다. 매뉴얼 01·07장과 부록 P-01에서 옛 목록을 전제로 쓴 문장을 같이 고친다. 줄 수는 그대로라 매뉴얼의 CLAUDE.md 줄 참조는 맞다. 버린 대안: 목록에 빠진 명령을 더 적기(다음에 게이트가 바뀌면 다시 갈라진다). merge 단계를 읽는 명령(ci:gate:stage merge)은 이 작업 범위 밖이라 더하지 않았다. 위험·한계: 리뷰 시작 비용이 커진다(FE-GATE-020만 약 20분). 실행 위치와 잠금은 매뉴얼 07장 7절을 따른다. 추적하지 않는 AGENTS.md는 이 변경을 받지 않는다. 검증: 로컬 정적 대조(매뉴얼의 경로·script·FE-GATE ID 문제 0건). desktop의 verify:documentation과 문서 unit 테스트는 이 커밋을 보내 돌린다. Refs: 1105/12-03
16 KiB
16 KiB
01. 작업 종류별 절차
핵심
개선 작업은 여섯 종류다. 리뷰, 결함 수정, 리팩터링, 성능 최적화, 구조 변경, 테스트 구조 개선. 종류마다 시작 조건 → 단계 → 산출물 → 완료 기준을 같은 틀로 적는다. 시작 조건이 안 맞으면 다른 종류의 작업이다.
종류를 고르는 기준은 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"다.
| 질문 | 답 | 작업 |
|---|---|---|
| 아직 무엇이 틀렸는지 모른다 | 찾는다 | 리뷰 |
| 계약과 다른 동작이 확인됐다 | 동작을 계약에 맞춘다 | 결함 수정 |
| 동작은 맞는데 구조 비용이 크다 | 동작을 그대로 두고 모양을 바꾼다 | 리팩터링 |
| 숫자로 잰 비용이 크다 | 같은 동작을 더 싸게 | 성능 최적화 |
| 최상위 폴더·adapter 그룹·기능 폴더·import 규칙이 바뀐다 | 경계를 바꾼다 | 구조 변경 |
| 테스트가 주장을 증명하지 못하거나 가끔 떨어진다 | 테스트를 고친다 | 테스트 구조 개선 |
0. 모든 작업의 공통 단계
- 기준 커밋을 고정한다.
git rev-parse HEAD를 산출물 첫머리에 적는다. 리뷰 문서는 모두 기준 커밋으로 시작한다(CLAUDE.md26줄, 1105 README 머리말). - 이전 기록을 읽는다. 가장 최근 리뷰 README의 「결정이 필요한 것」「조치」「남은 문제」 절과 08장 색인을 읽는다. 이미 정한 것을 다시 묻지 않는다(08장 3절).
- 위험을 정한다. 위험은 파일 수가 아니라 바뀌는 경계로 정한다. 사용자 데이터(결과 불명 쓰기, OPFS 개인 파일), 공개 포트, merge 게이트, 짝 백엔드 계약을 건드리면 높다. 높으면 설계와 대안을 먼저 적는다(가이드 41절).
- 스킬을 고른다. 소유자 규칙이다: 리뷰·수정에 스킬을 쓴다(2026-11-03~05 사용자 지시, 08장 표 O-3). 아래 표에서 고른다.
- 격리된 곳에서 일한다. 자기 worktree와 브랜치를 쓴다. 리뷰어는 코드를 고치지 않는다. 의심 결함은 임시
테스트로 확인하고 그 코드는 리뷰 문서나 scratchpad에만 남긴다(
CLAUDE.md15줄). - 무거운 실행 위치를 지킨다. 테스트·게이트·빌드는 노트북에서 돌리지 않는다(07장 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 「전체 리뷰 절차」 15단계다(2630줄). 아래는 그 단계를 지난 라운드에서 겪은 대로
구체화한 것이다.
- 범위를 고정한다. 기준 커밋, 브랜치, 확인 시점, 노트북 worktree와 desktop checkout이 깨끗한지 적는다 (1105 README 11절 표).
- 전제를 채운다. 전체 리뷰면 가이드 0.1절 전제 표를 채운다. 이 repo의 고정 전제는
CLAUDE.md「이 repo의 리뷰 전제」 네 줄이다. 템플릿에는 요청량·데이터량 목표가 없으므로 그 칸은 "기능 수 증가 축과 lab·번들 예산으로 판정"처럼 적는다(1105 README 0절). - 게이트를 한 번 돌린다.
CLAUDE.md2단계대로config/ci/gates.json의 merge 단계gateIds14개를 workflow env로ci:gate를 통해 돌리고,verify:documentation을 따로 돌린다(07장 3절). 예전에는 2단계가 명령 11개를 손으로 적었고, 그 목록만 돌려 실제 러너에서 항상 실패하는 게이트 두 개를 놓친 적이 있다(1103 README 10.5절 마지막 행, 1105/12-03). - 결과를 함께 읽는다. 게이트 출력과
artifacts/·dist/·test-results/를 읽기 전용 사본으로 떠 두고, 모든 리뷰어가 그 사본을 읽는다. 리뷰어마다 따로 돌리지 않는다(09장 4절). - 영역을 나눈다. 가장 최근 리뷰 README의 영역 표를 다시 쓴다. 지금은 16개 영역이다(1103 README 10.2절, 1105 README 11.2절). 영역마다 서브에이전트나 하위 세션 하나(09장).
- 영역을 읽는다. 영역 문서는 「지난 발견 재판정」부터 쓴다. 지난 라운드가 "고침"이라고 한 것도 코드로 다시 본다. 4라운드는 1103 조치의 "고침" 13건을 "일부"로 정정했다(1105 README 3.1절).
- 더 필요한 실험은 목록으로 낸다. 리뷰어가 직접 돌리지 않는다. 총괄이 모아 같은 명령은 한 번만, 실험마다 작업 폴더를 되돌리며 일괄로 돌린다(09장 4절).
- 발견을 02장 형식으로 적는다. 같은 결함을 두 영역이 적으면 색인에서 하나로 합치고 「합친 중복」 표에 남긴다(1105 README 11.3절).
- 총괄이 다시 확인한다. High 이상과 새 P1은 총괄이 코드를 직접 읽거나 실행해 확인하고, 재확인 칸에 그 사실을
적는다(
CLAUDE.md30줄, 1105 README 2.2절 「재확인」 칸). - 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.md29줄). - 리뷰 문서는 리뷰 시점 기록이다. 고친 뒤에도 영역 문서를 고치지 않는다. 처리 결과는 같은 README의 「조치」 절에 적는다(1103 README 14절). 틀린 문장이 남아도 리뷰 기록은 고치지 않고, 현재 문서(CHANGELOG 등)에서 바로잡는다 (1103 README 14.7절 끝).
완료 기준
- 모든 발견이 02장 형식이고 성격·심각도·우선순위·통제·증거가 따로 적혀 있다.
- 지난 라운드 발견 전부의 지금 상태가 표 하나에 있다(1105 README 13절).
- 미검증 목록과 확인 방법이 있다.
- 결정이 필요한 항목마다 선택지와 결정할 사람이 있다(1105 README 7절).
- 리뷰 중 코드를 고치지 않았고, 끝에 desktop checkout의
git status가 비었다.
2. 결함 수정
시작 조건
- 리뷰 문서의 발견 ID가 있다. 발견 없이 고치면 그 고침이 무엇을 막는지 아무도 모른다.
- 그 발견의 「완료 기준」 칸을 읽었다. 완료 기준의 기준은 그 칸이다(
SPEC.md13줄).
단계
- 재현 테스트를 먼저 쓴다(RED). 동작을 바꾸는 수정은 재현 테스트가 먼저 실패하고, 고친 뒤 통과한다. 브라우저
없이 재현할 수 없으면 fake·fixture로 조건을 만든다(
SPEC.md29줄). - 검출력을 확인한다. 테스트 검출력이 문제였던 발견(변이 생존)은 리뷰에 적힌 변이를 다시 넣어 새 테스트가
실패하는지 본다(
SPEC.md30줄). - 고친다(GREEN). 공개 포트는 추가만 한다. 기존 시그니처를 깨야 하면 결정 표에 적는다(
SPEC.md35줄). 공용 로직은src/adapters/platform/또는src/contracts/에 둔다. 새 파일 단위 예외를 만들지 않는다(SPEC.md34줄). - 수정이 새로 가정하는 것을 적는다. 커밋 본문 「위험·한계」에 쓴다. 4라운드 새 발견의 상당수가 지난 수정에서 나왔고, 수정마다 이 질문을 하는 단계가 없었다(1105 README 6절 원인 5).
- 템플릿 원래 상태 밖에서도 확인한다. 기능 하나를 더한 상태, 예제 기능을 지운 상태, 입력이 셋 이상인 상태로 한 번씩 돌린다. 템플릿 원래 상태나 작은 입력으로만 확인한 수정이 다시 결함이 됐다(1105 README 6절 원인 1, 부록 P-02).
- 커밋한다. 논리적 변경 하나에 커밋 하나, 커밋 메시지에 발견 ID, 그 작업이 바꾼 파일만 스테이징한다(
SPEC.md36줄, 08장 5절). - 빠른 게이트를 돌린다. 작업마다
SPEC.md31줄의 8개, 레인이 끝날 때와 통합 때는 32줄의 5개를 더 돌린다(07장 2절). - adapter 파일을 더하거나 옮기면
docs/reviews/adapters/INVENTORY.md를 같은 커밋에서 고친다(SPEC.md33줄).
산출물
- 커밋(
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절).
- 지켜야 할 동작·타입·실패·진단 계약을 적을 수 있다. 적을 수 없으면 리팩터링이 아니라 설계 변경이다.
단계
- 보존 조건을 먼저 적는다. 가이드 36.3절 「단순화의 보존 조건」, 39.9절.
- 기존 테스트가 그 조건을 지키는지 본다. 못 지키면 테스트부터 더한다(5절이 아니라 이 작업 안에서).
- 바꾼다. 이 repo의 고정 전제를 지킨다.
- 소비자 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이다. 지우지 않는다(
CLAUDE.md19줄). - 갈라진 중복 복사본은 하나로 합친다(같은 줄, 부록 P-14).
- adapter 배럴(
src/adapters/*/index.ts)이 공개 경계다. 배럴 밖으로 공개 표면을 늘리지 않는다(CLAUDE.md20줄).
- 소비자 없는 코드와 빈 레지스트리는 다운스트림용 확장 지점이다. 지우지 않는다(
- 같은 테스트가 그대로 통과한다. 테스트를 고쳐야 통과하면 동작이 바뀐 것이다. 결함 수정이나 설계 변경으로 다시 분류한다.
산출물
refactor(<scope>): ...커밋. 본문에 보존 조건과 버린 대안(커밋 규칙 3.3절).
완료 기준
- 테스트 변경 없이 빠른 게이트 8개가 통과한다.
- 줄어든 이해 비용을 한 문장으로 말할 수 있다(읽을 파일 수, 알아야 할 규약 수 등).
4. 성능 최적화
시작 조건
- 같은 조건에서 두 번 이상 잰 숫자가 있고, 예산을 넘거나 회귀했다(06장 2절).
- 그 숫자를 만든 측정 조건(위치·부하·반복 수·빌드)을 안다.
단계
- 기준선을 06장 3절 조건으로 다시 잰다. 예전 측정값을 기준선으로 쓰지 않는다.
- 원인을 좁힌다. 무엇이 비용을 만드는지 네트워크 waterfall·청크 목록·trace로 확인한다.
- 바꾼다. 초기 JS 예산·초기 파일 수 상한·lab 예산을 함께 본다. 하나를 줄이며 다른 하나를 넘기지 않는다(06장 4절).
- 같은 조건으로 다시 잰다. 대조군(바꾸기 전 커밋)을 같은 세션에서 함께 잰다.
- 기준선 파일을 고쳐야 하면 06장 5절 절차를 따른다.
산출물
- 전후 숫자와 측정 조건(06장 3절 항목 전부).
perf(<scope>): ...커밋.
완료 기준
check:bundle(FE-GATE-012)과 lab 게이트(test:performance, FE-GATE-026)가 통과한다.- 전후 차이가 측정 잡음보다 크다. 잡음 크기를 함께 적는다.
5. 구조 변경
시작 조건
- 최상위
src/폴더, adapter 그룹, 기능·context 경계, import 규칙 중 하나가 바뀐다.
단계
- 설계와 대안을 먼저 적는다(
superpowers:brainstorming→superpowers:writing-plans). 가이드 41절의 일곱 질문. - 03장의 구조 기준을 확인한다. 특히 새 파일 단위 kernel 예외를 만들지 않는다(
CLAUDE.md21줄). - 규칙과 문서를 코드와 같은 커밋에서 바꾼다.
- 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.ts101~152줄). - adapter 파일:
docs/reviews/adapters/INVENTORY.md.
- import 규칙:
- 제거 드릴을 돌린다. 지울 수 있는 단위(참조 기능, recipe, runtime)가 바뀌면 FE-GATE-020의 드릴이 그 변화를 안다 (03장 6절).
산출물
- 설계 문서(커밋 범위가 크면
docs/superpowers/plans/), 코드·규칙·문서를 함께 바꾼 커밋.
완료 기준
check:architecture,check:adapter-inventory,verify:documentation, FE-GATE-020이 통과한다.
6. 테스트 구조 개선
시작 조건
- 테스트가 주장을 증명하지 못한다(변이가 살아남는다, 템플릿 원래 상태만 본다). 또는 가끔 떨어진다.
단계
- 가끔 떨어지는 테스트는 05장 5절 절차로 원인을 찾는다. 재시도·timeout 늘리기·worker 줄이기로 덮지 않는다.
- 테스트 위치를
docs/testing/taxonomy.md의 층 기준으로 정한다. 프레임워크가 아니라 필요한 실행 환경이 층을 정한다(taxonomy 85~99줄). - 검출력은 변이로 확인한다. 고친 테스트가 원래 결함 변이를 잡는지 본다(
SPEC.md30줄). - 바뀐 테스트가 속한 게이트를 돌린다. 브라우저 테스트는 같은 조건에서 반복 실행 결과를 함께 적는다(05장 5절).
산출물
test(<scope>): ...또는fix(test): ...커밋. 본문에 원인, 결정적 재현 방법, 반복 실행 결과.
완료 기준
- 변이 또는 결정적 재현이 고친 뒤 기대대로 실패·통과한다.
- 반복 실행에서 실패 0이다. 횟수를 적는다(1103/11-10은 고친 뒤 30회 반복, 660/660 통과).
지금 이해하면 되는 것
- 작업 종류는 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"로 고른다.
- 결함 수정은 RED 먼저, 발견 ID와 함께, 템플릿 원래 상태 밖에서도 확인한다.
- 리뷰는 코드를 고치지 않고, 게이트는 한 번 돌려 모두가 함께 읽는다.