Files
clean-architecture-backend-…/docs/improvement/01-procedures.md
T
DongHyeonka 3b66358e52 docs(improvement): 리뷰·개선 작업 매뉴얼을 만든다
문제: 이 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에서 돌린다.
2026-11-05 21:59:44 +09:00

14 KiB

01. 작업 종류별 절차

핵심

개선 작업은 여섯 종류다. 리뷰, 결함 수정, 리팩터링, 성능 최적화, 구조 변경, 테스트 구조 개선. 종류마다 시작 조건 → 단계 → 산출물 → 완료 기준을 같은 틀로 적는다. 시작 조건이 안 맞으면 다른 종류의 작업이다.

종류를 고르는 기준은 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"다.

질문 답 작업
아직 무엇이 틀렸는지 모른다 찾는다 리뷰
계약과 다른 동작이 확인됐다 동작을 계약에 맞춘다 결함 수정
동작은 맞는데 구조 비용이 크다 동작을 그대로 두고 모양을 바꾼다 리팩터링
숫자로 잰 비용이 크다 같은 동작을 더 싸게 성능 최적화
leaf·패키지·의존 방향이 바뀐다 경계를 바꾼다 구조 변경
테스트가 주장을 증명하지 못한다 테스트를 고친다 테스트 구조 개선

0. 모든 작업의 공통 단계

  1. 기준 커밋을 고정한다. git rev-parse HEAD를 산출물에 적는다. 리뷰 문서는 모두 기준 커밋으로 시작한다 (1101 README 머리말, 1103 README 머리말).
  2. 이전 기록을 읽는다. 가장 최근 리뷰 README의 「결정」「남은 것」 절과 08장 색인을 읽는다. 이미 정한 것을 다시 묻지 않는다(08장 2절). 같은 리뷰를 모르고 다시 시작하면 지난 결정과 다른 답이 나온다.
  3. 위험을 정한다. 위험은 파일 수가 아니라 바뀌는 경계와 런타임·보안·데이터·공개 계약 영향으로 정한다 (CLAUDE.md 「Proportional workflow」, AGENTS.md 「Gradle 정책 권위」 끝 문단). 위험이 높으면 설계서와 단계별 리뷰를 둔다.
  4. 소유 leaf를 찾는다. registry의 source_path로 소유 leaf를 정하고, 가장 가까운 src/**/CLAUDE.md를 읽는다 (AGENTS.md 「Gradle 정책 권위」).
  5. 스킬을 고른다. 아래 표에서 고른다. AGENTS.md 「Superpowers Workflow」가 스킬과 트리거의 정본이다.
  6. 격리된 곳에서 일한다. 자기 worktree와 브랜치를 쓴다(superpowers:using-git-worktrees). 리뷰어의 실험도 별도 worktree에서 한다(1103 README 머리말 "의심 결함은 별도 worktree의 임시 테스트로 확인").
  7. 무거운 실행 위치를 지킨다. 07장 「소유자 환경」.
  8. 보고 전에 검증한다. superpowers:verification-before-completion. 돌리지 못한 검증은 이유와 함께 적는다 (AGENTS.md HARD-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>).
  • 기준 커밋과 이전 라운드의 결정·남은 것을 읽었다.

단계

  1. 범위를 고정한다. 확인 리뷰는 pathspec과 git diff --stat <base>..<head> -- <pathspec> 결과를 적는다 (1103/round6/01-core-inbound.md 「pathspec」).
  2. 전체 리뷰면 가이드 0.1 전제 표(목적·실행 형태·규모 목표…)를 채운다. 템플릿에는 지연·처리량 목표가 없으므로 그 칸은 "목표 없음 — 요청당 비용과 비례 여부로 판정"처럼 적는다(1101/09-performance-measurement.md 1절).
  3. 전체 리뷰면 게이트를 먼저 한 번 돌려 결과를 적는다(1101 README 9절). 확인 리뷰는 고친 묶음이 적은 검증을 다시 돌릴 필요가 있는 것만 돌린다.
  4. 영역을 나눈다. 가장 최근 README의 영역 표를 다시 쓴다(1101 README 9절 9영역, 1103 README 2절 7영역, round6 4영역). 영역마다 하위 세션 하나(09장).
  5. 영역을 읽는다. 의심 결함은 별도 worktree의 임시 테스트(탐침)로 확인한다. 탐침 코드는 고칠 때 fixture로 옮겨 쓸 수 있게 남긴다(1103/round6/01-core-inbound.md 「실행한 명령과 결과」).
  6. 발견을 02장 형식으로 적는다. 같은 결함을 두 영역이 적으면 색인에서 하나로 합친다(1101 README 2절).
  7. 총괄은 High·Important 이상을 코드에서 직접 다시 확인한다(1101 README 2절 "코드 확인").
  8. 색인을 만든다. 영역 문서의 ID를 손으로 옮기지 말고 문서에서 기계적으로 모은다. 손으로 옮기다 5건이 빠져 어떤 수정 묶음에도 배정되지 않은 적이 있다(1101 README 12절 정정, 1103 README 1절).

산출물

  • 전체 리뷰: docs/reviews/<YYYY-MM-DD>-maturity-review/README.md + 영역 문서 NN-<영역>.md.
  • 확인 리뷰: 해당 리뷰 폴더 아래 roundN/(예: docs/reviews/2026-11-03-rereview/round6/).
  • 리뷰 문서는 리뷰 시점 기록이다. 수정 뒤에도 영역 문서를 고치지 않고, 처리 결과는 README에 적는다 (1101 README 머리말).

완료 기준

  • 모든 발견이 02장 형식이고 증거 수준이 적혀 있다.
  • 미검증 목록과 이유가 있다.
  • 결정이 필요한 항목마다 선택지와 권하는 안이 있다(1101 README 5절).
  • 「Declined to judge」(판단하지 않음)로 둔 항목은 총괄이 다음 수정 묶음에 배정하거나 결정으로 닫는다. 판단하지 않은 채 다음 라운드로 넘기지 않는다(09장 5절).

2. 결함 수정

시작 조건

  • 결함이 02장 형식으로 적혀 있다(근거·발생 조건·영향).
  • 그 결함에 소유자 결정이 필요하면 결정이 났다. 결정 없이 고칠 수 있는 결함부터 먼저 고친다 (1101 README 7절 개선 순서 1).

단계

  1. 원인을 확인한다(superpowers:systematic-debugging). 증상이 아니라 원인 경로를 적는다.
  2. RED: 결함을 재현하는 테스트를 먼저 쓰고, 수정 전 코드에서 실패하는 것을 실행으로 본다. 실패 메시지를 기록한다(05장 4절). 수정 전 실패가 없는 수정은 완료가 아니다(1101 README 7절 완료 기준 "수정 전 실패하는 테스트가 있어야 한다").
  3. 가장 작은 수정으로 GREEN.
  4. 같은 원인의 다른 자리를 찾는다. 결과 불명 처리처럼 경계마다 다시 구현된 규칙은 한 경계만 고치면 다른 경계에서 다시 갈라진다(1101 README 4절 원인 1).
  5. 그 동작을 설명하는 문서를 같은 변경에서 고친다: 계약(docs/web/http-contract.md), runbook, 매뉴얼, leaf README·CLAUDE.md, Javadoc, 레지스트리(docs/registries/). 고친 뒤 옛 표현을 grep으로 찾는다(04장 P2).
  6. 파생 서비스의 동작이 바뀌면 업그레이드 안내(docs/upgrade/2026-11-maturity-review.md 형식)에 행을 더하고 커밋 제목에 !를 붙인다(08장 4절).
  7. 영향 leaf check와 관련 lane을 돌린다(07장).

산출물

  • 테스트, 코드, 문서 변경.
  • 리뷰 README 처리 표의 한 행: 발견 ID · 상태 · 검증(명령과 테스트 수) · RED(수정 전 실패한 테스트 이름) · 처리 내용 · 결정·남은 것(1101 README 13절 표, 1103 README 6절 표).

완료 기준

  • RED가 수정 전에 실패했고 GREEN이 수정 뒤 통과했다. 둘 다 실행 기록이 있다.
  • 같은 원인의 다른 자리를 확인했다.
  • 07장의 해당 게이트가 통과했다.
  • 확인 리뷰가 "닫힘"으로 판정했다(02장 8.2절 「항목 재확인」).

3. 리팩터링

시작 조건

  • 동작을 바꾸지 않는다고 말할 수 있다. 동작이 바뀌면 결함 수정이나 구조 변경이다.
  • 근거가 있다: 리뷰 발견, 부록 패턴(특히 A1 갈라진 복사본), 또는 03·04장 기준 위반.

단계

  1. 보존 조건을 적는다. 지킬 동작·타입·실패·진단 계약이다(가이드 36.3 「단순화의 보존 조건」, 39.9).
  2. 보존 조건을 지키는 테스트가 있는지 본다. 없으면 먼저 쓰고 지금 코드에서 통과하는 것을 본다.
  3. 작은 단계로 바꾼다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다(커밋 규칙 3.1).
  4. 복사본을 합칠 때는 정본 하나를 정하고 나머지를 지운다. 지울 수 없으면 이유를 가까운 CLAUDE.md에 적고 두 벌이 같은지 보는 대조 테스트를 둔다. 예:
    • vendored family는 registry edge가 없어 복사본을 유지하고 이유를 family CLAUDE.md에 적었다 (1101 README 15절 01-11 결정, src/messaging/CLAUDE.md 「공용 다이제스트 헬퍼를 복사해 두는 이유」).
    • messaging은 persistence-jpa에 의존할 수 없어 Flyway 정책 값을 사본으로 두고 대조 테스트를 붙였다 (1103 README 17절 r10-03).
  5. 공개 API 표면이 바뀌면 API surface 검사가 PR에서 잡는다(결정 20). 의도한 변경이면 스냅숏을 갱신한다 (docs/architecture/*-api-surface.txt).

산출물

  • 구조 변경 커밋(refactor:), 지운 복사본 목록, 남긴 사본과 그 이유.

완료 기준

  • 보존 조건 테스트가 변경 전후 모두 통과한다.
  • architectureCheck가 통과한다.
  • 지운 코드를 가리키던 문서·주석이 없다(grep 결과를 보고에 적는다).

4. 성능 최적화

시작 조건

  • 측정한 숫자가 있다. 추측으로 시작하지 않는다. 이 템플릿에는 지연·처리량 목표가 없으므로 "요청당 비용이 데이터 수에 비례해 늘어난다" 같은 측정된 사실이 시작점이다(1101/09-performance-measurement.md 1절).

단계

  1. 06장 조건으로 기준선을 잰다.
  2. 원인을 좁힌다: 요청당 SQL 수, JFR 상위 프레임, 설정만 바꾼 실험(06장 3절).
  3. 변경 하나만 넣는다.
  4. 같은 조건으로 다시 잰다. 전후 숫자를 같은 표에 적는다.
  5. 회귀를 테스트로 고정한다. 예: 요청당 SQL 수를 단언하는 WorkLogStatementCostSystemTest(06장 6절).

산출물

  • 측정 조건·명령·전후 숫자·회귀 테스트.

완료 기준

  • 전후 숫자가 같은 조건(커밋 외 변수 하나)에서 나왔다.
  • 회귀 테스트가 어떤 단계에 속한다(verifyStrictLaneStages가 통과).

5. 구조 변경 (폴더·모듈)

시작 조건

  • leaf 추가·삭제·이동, 패키지 이동, 허용 의존 변경 중 하나다. 위험이 높은 작업으로 다룬다 (CLAUDE.md 「Proportional workflow」).
  • 새 leaf 등록은 소유자 승인을 받는다(1101 README 15절 "새 leaf … 등록 | 승인").

단계

  1. superpowers:brainstorming으로 설계를 정하고 docs/superpowers/specs/에 설계서를 둔다.
  2. docs/superpowers/plans/에 계획을 둔다(AGENTS.md 「기능 개발 프로토콜」 3~4).
  3. 03장 체크리스트대로 registry·build·lockfile·문서를 함께 바꾼다.
  4. 규칙이 바뀌면 ArchUnit 규칙을 함께 바꾼다. 규칙마다 잡혀야 할 위반 fixture와 통과해야 할 허용 fixture를 둘 다 둔다(05장 5절).
  5. 패키지 규칙이 바뀌면 생성 명령 왕복(verifyFeatureScaffold)이 통과해야 한다(src/build.gradle의 verifyFeatureScaffold).
  6. 파생 서비스가 따라 할 업그레이드 안내를 쓴다.

산출물

  • 설계서, 계획서, 구조 변경 커밋, 업그레이드 안내 행.

완료 기준

  • architectureCheck, verifyDependencyLocks, ci, mainCheck(생성 명령 왕복 포함)가 통과한다.
  • leaf 개수를 문서에 적지 않았다(AGENTS.md 「Gradle 정책 권위」).

6. 테스트 구조 개선

시작 조건

  • 05장 기준 위반이 있다: 이름이 말한 성질을 단언하지 않음, 포트 계약 밖의 fake, 어떤 단계에도 속하지 않는 lane, 실패한 채 방치된 테스트 코드 정적 분석 등.

단계

  1. 지금 테스트가 무엇을 증명하는지 적는다(이름, 단언, skip 수).
  2. 05장 기준대로 고친다. fake를 공유 계약으로 옮기면 fake와 실제 adapter가 모두 그 계약을 상속하게 한다.
  3. 변이로 확인한다. 테스트가 지키려는 production 코드를 일부러 망가뜨려 테스트가 실패하는지 본다. 예: fake 변이 6개를 모두 계약이 잡았다(1101 README 16절 r3-b).
  4. 옮긴 뒤 같은 수의 테스트가 같은 lane에서 도는지 테스트 수로 확인한다.

산출물

  • 테스트 변경, 변이 결과, 계약 표 갱신(docs/testing/TESTING_STRATEGY.md 9절처럼 표가 있으면).

완료 기준

  • 변이가 잡혔다.
  • 새 lane이 단계에 속한다(verifyStrictLaneStages --dry-run).
  • testQualityCheck가 통과한다(07장).

지금 이해하면 되는 것

  • 작업 종류는 "동작이 바뀌는가"와 "무엇을 근거로 시작하는가"로 고른다.
  • 결함 수정은 RED(수정 전 실패) 없이 끝나지 않는다.
  • 어느 작업이든 기준 커밋, 이전 결정, 소유 leaf, 스킬, 검증 위치부터 정한다.