문제: 이 repo를 리뷰하거나 결함 수정·리팩터링·성능 최적화·구조 변경을 할 때 기준으로 삼을 문서가 없다. docs/manual/은 새 기능을 만드는 순서이고, 리뷰 기준으로 써 온 공용 가이드는 프론트 repo에만 있으며 AGENTS.md·CLAUDE.md가 가리키지 않는다. 2026-11-01부터 쌓인 소유자 결정과 반복 결함 패턴은 리뷰 문서 여러 곳에 흩어져 있다. 방법: docs/improvement/에 README, 01~09장, 결함 패턴 부록을 둔다. 규칙은 다시 쓰지 않고 정본(AGENTS.md, modules.json, application-core/CLAUDE.md, TESTING_STRATEGY.md, src/build.gradle, 리뷰 문서의 결정 절)을 가리킨다. 정본이 없는 것 — 작업 종류별 절차, 이 repo의 28개 관점 점검 항목과 결함 정의, 반복 결함 패턴, 성능 측정 조건, 무거운 실행 위치, 결정 색인, 세션 분업과 리뷰 반복 종료 조건 — 만 매뉴얼이 정본이 된다. AGENTS.md에 「리뷰·개선 작업 기준」 절, CLAUDE.md에 그 요약을 두고 docs/README.md와 docs/manual/README.md에서 가리킨다. 프론트 매뉴얼과 같은 장 번호를 쓴다. 버린 대안: docs/reviews/ 안에 두기(결과 보관소와 기준서가 섞인다), 공용 가이드 복사(갈라진 복사본이 된다), 소유자 환경 규칙을 AGENTS.md에 직접 쓰기(파생 프로젝트가 정책 문서를 고쳐야 한다). 위험·한계: 매뉴얼을 정본과 대조하는 자동 검사는 없다(문서 파서를 두지 않는 repo 방침). 08장 결정 표는 색인이고 원문과 다르면 원문이 맞다. 저장소 밖 문서(공용 가이드, 커밋 규칙)는 lychee가 따라갈 수 없어 링크 대신 코드 표기로 썼다. 근거를 찾지 못한 것 하나(측정 스크립트를 scripts/perf/로 넣기)는 [제안]으로 표시했다. 검증: 인용한 저장소 경로·리뷰 ID·클래스 이름·태스크 이름·상대 링크·절 번호를 스크립트로 전수 대조했다(로컬, 읽기만). 남은 불일치는 저장소 밖 가이드 경로, 자리표시자, 제안 경로, 원래 있던 문장뿐이다. CLAUDE.md는 DeveloperExperienceContractTest가 요구하는 architectureTest 명령을 그대로 둔다. 문서 대조 lane은 이 커밋을 push한 뒤 desktop에서 돌린다.
14 KiB
14 KiB
01. 작업 종류별 절차
핵심
개선 작업은 여섯 종류다. 리뷰, 결함 수정, 리팩터링, 성능 최적화, 구조 변경, 테스트 구조 개선. 종류마다 시작 조건 → 단계 → 산출물 → 완료 기준을 같은 틀로 적는다. 시작 조건이 안 맞으면 다른 종류의 작업이다.
종류를 고르는 기준은 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"다.
| 질문 | 답 | 작업 |
|---|---|---|
| 아직 무엇이 틀렸는지 모른다 | 찾는다 | 리뷰 |
| 계약과 다른 동작이 확인됐다 | 동작을 계약에 맞춘다 | 결함 수정 |
| 동작은 맞는데 구조 비용이 크다 | 동작을 그대로 두고 모양을 바꾼다 | 리팩터링 |
| 숫자로 잰 비용이 크다 | 같은 동작을 더 싸게 | 성능 최적화 |
| leaf·패키지·의존 방향이 바뀐다 | 경계를 바꾼다 | 구조 변경 |
| 테스트가 주장을 증명하지 못한다 | 테스트를 고친다 | 테스트 구조 개선 |
0. 모든 작업의 공통 단계
- 기준 커밋을 고정한다.
git rev-parse HEAD를 산출물에 적는다. 리뷰 문서는 모두 기준 커밋으로 시작한다 (1101README 머리말,1103README 머리말). - 이전 기록을 읽는다. 가장 최근 리뷰 README의 「결정」「남은 것」 절과 08장 색인을 읽는다. 이미 정한 것을 다시 묻지 않는다(08장 2절). 같은 리뷰를 모르고 다시 시작하면 지난 결정과 다른 답이 나온다.
- 위험을 정한다. 위험은 파일 수가 아니라 바뀌는 경계와 런타임·보안·데이터·공개 계약 영향으로 정한다
(
CLAUDE.md「Proportional workflow」,AGENTS.md「Gradle 정책 권위」 끝 문단). 위험이 높으면 설계서와 단계별 리뷰를 둔다. - 소유 leaf를 찾는다. registry의
source_path로 소유 leaf를 정하고, 가장 가까운src/**/CLAUDE.md를 읽는다 (AGENTS.md「Gradle 정책 권위」). - 스킬을 고른다. 아래 표에서 고른다.
AGENTS.md「Superpowers Workflow」가 스킬과 트리거의 정본이다. - 격리된 곳에서 일한다. 자기 worktree와 브랜치를 쓴다(
superpowers:using-git-worktrees). 리뷰어의 실험도 별도 worktree에서 한다(1103README 머리말 "의심 결함은 별도 worktree의 임시 테스트로 확인"). - 무거운 실행 위치를 지킨다. 07장 「소유자 환경」.
- 보고 전에 검증한다.
superpowers:verification-before-completion. 돌리지 못한 검증은 이유와 함께 적는다 (AGENTS.mdHARD-STOP 6).
스킬 고르기
| 작업 | 절차 스킬 | 영역 스킬(바뀌는 경계에 맞춰) | 근거 |
|---|---|---|---|
| 리뷰 | superpowers:requesting-code-review(리뷰어 템플릿) |
clean-architecture, domain-driven-design, codebase-design, api-and-interface-design, security-and-hardening, jpa-patterns, supabase-postgres-best-practices, performance-optimization, observability-and-instrumentation, ci-cd-and-automation, refactor, documentation-and-adrs, doubt-driven-development |
1103 README 2절 표, 1103/round5/review.md 「불러온 스킬과 적용한 기준」 |
| 리뷰 결과를 받아 고칠 때 | superpowers:receiving-code-review |
— | AGENTS.md 「Superpowers Workflow」 |
| 결함 수정 | superpowers:systematic-debugging → superpowers:test-driven-development |
바뀌는 경계의 영역 스킬 | 1103 README 6·10·12절 "test-driven-development 스킬 절차로 RED→GREEN" |
| 리팩터링 | refactor, codebase-design |
clean-architecture |
1103 README 2절(06 영역 refactor) |
| 성능 최적화 | performance-optimization |
jpa-patterns, supabase-postgres-best-practices |
1103 README 2절(04 영역) |
| 구조 변경 | superpowers:brainstorming → superpowers:writing-plans |
clean-architecture |
AGENTS.md 「기능 개발 프로토콜」 2~4 |
| 테스트 구조 개선 | superpowers:test-driven-development |
— | AGENTS.md 「Superpowers Workflow」 |
| 문서·결정 기록 | documentation-and-adrs |
— | 1103 README 2절(06 영역) |
| 완료 주장 전 | superpowers:verification-before-completion |
— | AGENTS.md 「테스트 전략」 검증 원칙 |
리뷰어는 불러온 스킬과 그 스킬에서 적용한 기준을 리뷰 문서 「범위」 절에 표로 적는다(02장 8.2절). 스킬을 불렀다는 사실보다 그 기준으로 무엇을 봤는지가 증거다.
1. 리뷰
시작 조건
- 대상이 정해졌다: 전체, 영역, 또는 커밋 범위(
<base>..<head>). - 기준 커밋과 이전 라운드의 결정·남은 것을 읽었다.
단계
- 범위를 고정한다. 확인 리뷰는 pathspec과
git diff --stat <base>..<head> -- <pathspec>결과를 적는다 (1103/round6/01-core-inbound.md「pathspec」). - 전체 리뷰면 가이드 0.1 전제 표(목적·실행 형태·규모 목표…)를 채운다. 템플릿에는 지연·처리량 목표가 없으므로
그 칸은 "목표 없음 — 요청당 비용과 비례 여부로 판정"처럼 적는다(
1101/09-performance-measurement.md1절). - 전체 리뷰면 게이트를 먼저 한 번 돌려 결과를 적는다(
1101README 9절). 확인 리뷰는 고친 묶음이 적은 검증을 다시 돌릴 필요가 있는 것만 돌린다. - 영역을 나눈다. 가장 최근 README의 영역 표를 다시 쓴다(
1101README 9절 9영역,1103README 2절 7영역,round64영역). 영역마다 하위 세션 하나(09장). - 영역을 읽는다. 의심 결함은 별도 worktree의 임시 테스트(탐침)로 확인한다. 탐침 코드는 고칠 때 fixture로
옮겨 쓸 수 있게 남긴다(
1103/round6/01-core-inbound.md「실행한 명령과 결과」). - 발견을 02장 형식으로 적는다. 같은 결함을 두 영역이 적으면 색인에서 하나로 합친다(
1101README 2절). - 총괄은 High·Important 이상을 코드에서 직접 다시 확인한다(
1101README 2절 "코드 확인"). - 색인을 만든다. 영역 문서의 ID를 손으로 옮기지 말고 문서에서 기계적으로 모은다. 손으로 옮기다 5건이 빠져
어떤 수정 묶음에도 배정되지 않은 적이 있다(
1101README 12절 정정,1103README 1절).
산출물
- 전체 리뷰:
docs/reviews/<YYYY-MM-DD>-maturity-review/README.md+ 영역 문서NN-<영역>.md. - 확인 리뷰: 해당 리뷰 폴더 아래
roundN/(예:docs/reviews/2026-11-03-rereview/round6/). - 리뷰 문서는 리뷰 시점 기록이다. 수정 뒤에도 영역 문서를 고치지 않고, 처리 결과는 README에 적는다
(
1101README 머리말).
완료 기준
- 모든 발견이 02장 형식이고 증거 수준이 적혀 있다.
- 미검증 목록과 이유가 있다.
- 결정이 필요한 항목마다 선택지와 권하는 안이 있다(
1101README 5절). - 「Declined to judge」(판단하지 않음)로 둔 항목은 총괄이 다음 수정 묶음에 배정하거나 결정으로 닫는다. 판단하지 않은 채 다음 라운드로 넘기지 않는다(09장 5절).
2. 결함 수정
시작 조건
- 결함이 02장 형식으로 적혀 있다(근거·발생 조건·영향).
- 그 결함에 소유자 결정이 필요하면 결정이 났다. 결정 없이 고칠 수 있는 결함부터 먼저 고친다
(
1101README 7절 개선 순서 1).
단계
- 원인을 확인한다(
superpowers:systematic-debugging). 증상이 아니라 원인 경로를 적는다. - RED: 결함을 재현하는 테스트를 먼저 쓰고, 수정 전 코드에서 실패하는 것을 실행으로 본다. 실패 메시지를
기록한다(05장 4절). 수정 전 실패가 없는 수정은 완료가 아니다(
1101README 7절 완료 기준 "수정 전 실패하는 테스트가 있어야 한다"). - 가장 작은 수정으로 GREEN.
- 같은 원인의 다른 자리를 찾는다. 결과 불명 처리처럼 경계마다 다시 구현된 규칙은 한 경계만 고치면 다른 경계에서
다시 갈라진다(
1101README 4절 원인 1). - 그 동작을 설명하는 문서를 같은 변경에서 고친다: 계약(
docs/web/http-contract.md), runbook, 매뉴얼, leaf README·CLAUDE.md, Javadoc, 레지스트리(docs/registries/). 고친 뒤 옛 표현을 grep으로 찾는다(04장 P2). - 파생 서비스의 동작이 바뀌면 업그레이드 안내(
docs/upgrade/2026-11-maturity-review.md형식)에 행을 더하고 커밋 제목에!를 붙인다(08장 4절). - 영향 leaf
check와 관련 lane을 돌린다(07장).
산출물
- 테스트, 코드, 문서 변경.
- 리뷰 README 처리 표의 한 행: 발견 ID · 상태 · 검증(명령과 테스트 수) · RED(수정 전 실패한 테스트 이름) ·
처리 내용 · 결정·남은 것(
1101README 13절 표,1103README 6절 표).
완료 기준
- RED가 수정 전에 실패했고 GREEN이 수정 뒤 통과했다. 둘 다 실행 기록이 있다.
- 같은 원인의 다른 자리를 확인했다.
- 07장의 해당 게이트가 통과했다.
- 확인 리뷰가 "닫힘"으로 판정했다(02장 8.2절 「항목 재확인」).
3. 리팩터링
시작 조건
- 동작을 바꾸지 않는다고 말할 수 있다. 동작이 바뀌면 결함 수정이나 구조 변경이다.
- 근거가 있다: 리뷰 발견, 부록 패턴(특히 A1 갈라진 복사본), 또는 03·04장 기준 위반.
단계
- 보존 조건을 적는다. 지킬 동작·타입·실패·진단 계약이다(가이드 36.3 「단순화의 보존 조건」, 39.9).
- 보존 조건을 지키는 테스트가 있는지 본다. 없으면 먼저 쓰고 지금 코드에서 통과하는 것을 본다.
- 작은 단계로 바꾼다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다(커밋 규칙 3.1).
- 복사본을 합칠 때는 정본 하나를 정하고 나머지를 지운다. 지울 수 없으면 이유를 가까운
CLAUDE.md에 적고 두 벌이 같은지 보는 대조 테스트를 둔다. 예:- vendored family는 registry edge가 없어 복사본을 유지하고 이유를 family
CLAUDE.md에 적었다 (1101README 15절 01-11 결정,src/messaging/CLAUDE.md「공용 다이제스트 헬퍼를 복사해 두는 이유」). - messaging은 persistence-jpa에 의존할 수 없어 Flyway 정책 값을 사본으로 두고 대조 테스트를 붙였다
(
1103README 17절 r10-03).
- vendored family는 registry edge가 없어 복사본을 유지하고 이유를 family
- 공개 API 표면이 바뀌면 API surface 검사가 PR에서 잡는다(결정 20). 의도한 변경이면 스냅숏을 갱신한다
(
docs/architecture/*-api-surface.txt).
산출물
- 구조 변경 커밋(
refactor:), 지운 복사본 목록, 남긴 사본과 그 이유.
완료 기준
- 보존 조건 테스트가 변경 전후 모두 통과한다.
architectureCheck가 통과한다.- 지운 코드를 가리키던 문서·주석이 없다(grep 결과를 보고에 적는다).
4. 성능 최적화
시작 조건
- 측정한 숫자가 있다. 추측으로 시작하지 않는다. 이 템플릿에는 지연·처리량 목표가 없으므로 "요청당 비용이 데이터
수에 비례해 늘어난다" 같은 측정된 사실이 시작점이다(
1101/09-performance-measurement.md1절).
단계
- 06장 조건으로 기준선을 잰다.
- 원인을 좁힌다: 요청당 SQL 수, JFR 상위 프레임, 설정만 바꾼 실험(06장 3절).
- 변경 하나만 넣는다.
- 같은 조건으로 다시 잰다. 전후 숫자를 같은 표에 적는다.
- 회귀를 테스트로 고정한다. 예: 요청당 SQL 수를 단언하는
WorkLogStatementCostSystemTest(06장 6절).
산출물
- 측정 조건·명령·전후 숫자·회귀 테스트.
완료 기준
- 전후 숫자가 같은 조건(커밋 외 변수 하나)에서 나왔다.
- 회귀 테스트가 어떤 단계에 속한다(
verifyStrictLaneStages가 통과).
5. 구조 변경 (폴더·모듈)
시작 조건
- leaf 추가·삭제·이동, 패키지 이동, 허용 의존 변경 중 하나다. 위험이 높은 작업으로 다룬다
(
CLAUDE.md「Proportional workflow」). - 새 leaf 등록은 소유자 승인을 받는다(
1101README 15절 "새 leaf … 등록 | 승인").
단계
superpowers:brainstorming으로 설계를 정하고docs/superpowers/specs/에 설계서를 둔다.docs/superpowers/plans/에 계획을 둔다(AGENTS.md「기능 개발 프로토콜」 3~4).- 03장 체크리스트대로 registry·build·lockfile·문서를 함께 바꾼다.
- 규칙이 바뀌면 ArchUnit 규칙을 함께 바꾼다. 규칙마다 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 둘 다 둔다(05장 5절).
- 패키지 규칙이 바뀌면 생성 명령 왕복(
verifyFeatureScaffold)이 통과해야 한다(src/build.gradle의verifyFeatureScaffold). - 파생 서비스가 따라 할 업그레이드 안내를 쓴다.
산출물
- 설계서, 계획서, 구조 변경 커밋, 업그레이드 안내 행.
완료 기준
architectureCheck,verifyDependencyLocks,ci,mainCheck(생성 명령 왕복 포함)가 통과한다.- leaf 개수를 문서에 적지 않았다(
AGENTS.md「Gradle 정책 권위」).
6. 테스트 구조 개선
시작 조건
- 05장 기준 위반이 있다: 이름이 말한 성질을 단언하지 않음, 포트 계약 밖의 fake, 어떤 단계에도 속하지 않는 lane, 실패한 채 방치된 테스트 코드 정적 분석 등.
단계
- 지금 테스트가 무엇을 증명하는지 적는다(이름, 단언, skip 수).
- 05장 기준대로 고친다. fake를 공유 계약으로 옮기면 fake와 실제 adapter가 모두 그 계약을 상속하게 한다.
- 변이로 확인한다. 테스트가 지키려는 production 코드를 일부러 망가뜨려 테스트가 실패하는지 본다. 예: fake
변이 6개를 모두 계약이 잡았다(
1101README 16절 r3-b). - 옮긴 뒤 같은 수의 테스트가 같은 lane에서 도는지 테스트 수로 확인한다.
산출물
- 테스트 변경, 변이 결과, 계약 표 갱신(
docs/testing/TESTING_STRATEGY.md9절처럼 표가 있으면).
완료 기준
- 변이가 잡혔다.
- 새 lane이 단계에 속한다(
verifyStrictLaneStages --dry-run). testQualityCheck가 통과한다(07장).
지금 이해하면 되는 것
- 작업 종류는 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"로 고른다.
- 결함 수정은 RED(수정 전 실패) 없이 끝나지 않는다.
- 어느 작업이든 기준 커밋, 이전 결정, 소유 leaf, 스킬, 검증 위치부터 정한다.