Files
clean-architecture-backend-…/docs/work/improve.md
T
DongHyeonka 06f520e667 docs(work): 성능 lane 단언 강제와 캐시 결과의 한계를 매뉴얼에 맞춘다
문제: 성능 lane 단언을 빌드가 강제하게 된 뒤에도 docs/work/는 옛 동작을
안내했다. gates.md 5절은 "desktop에서 -Pperformance.assertions.enabled=true를
준다. 안 주면 httpclient의 시간 단언 없이 통과한다"고 했고, 3절 라운드 끝
명령과 improve.md·operate.md의 「자주 하는 실수」도 그 속성을 맞추라고 했다.
지금은 convention이 단언을 켜고 true 아닌 값이나 skip이 있으면 테스트 전에
실패하므로, 그 문장은 틀렸고 그 속성은 필요 없다. 또 2026-11-06 B3 desktop
ci rc=0은 캐시 결과(태스크 701개 중 403개)였는데, 그 사이 httpclient
CircuitBreakerStatusAccountingTest 2건은 기준 커밋에서도 10번 중 10번 실패하고
있었다. 캐시 결과를 현재 통과의 증거로 쓰면 이런 기존 결함을 놓친다.

고른 방법:
- gates.md 5절을 새 동작으로 다시 쓰고(정본 AGENTS.md 「Gradle 정책 권위」,
  docs/testing/TESTING_STRATEGY.md), 1절 표와 6절 거짓 통과 표를 맞췄다.
  3절 명령에서는 그 속성을 뺐다. workflow도 이제 주지 않는다.
- improve.md의 같은 실수 줄은 지웠다. 빌드가 막으므로 더는 실수가 아니다.
- operate.md 「자주 하는 실수」의 그 줄 자리에 캐시 교훈을 넣었다: 기준 상태와
  시간·환경에 민감한 테스트는 그 태스크를 --rerun으로 다시 돌린다. gates.md
  6절에도 한 줄, 근거는 evidence.md 2절, 결정은 decisions.md 2.7, 장치는
  defect-patterns.md A7에 더했다.

위험·한계: --rerun은 지정한 태스크 하나만 다시 돈다. 집계 태스크 전체를 캐시
없이 돌리려면 --rerun-tasks가 필요하고 시간이 훨씬 길다. 이 매뉴얼은 그 둘을
가르는 기준까지는 정하지 않았다.

검증
- python3 scripts/check-work-docs.py: rc=0, 본문 이력 ID 0줄, improve.md
  131/150, operate.md 115/150
- python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md
  AGENTS.md: 깨진 링크 0
2026-11-06 21:30:26 +09:00

12 KiB

개선 — 리뷰, 결함 수정, 리팩터링, 성능, 구조, 테스트 구조

이미 있는 코드를 평가하거나 고치는 일의 절차다. 핵심은 하나다: 리뷰 → 수정 → 확인 리뷰를 발견이 0이 될 때까지 돈다.

1. 언제 쓰나

지금 상태 작업
무엇이 틀렸는지 아직 모른다 리뷰
계약(이름·Javadoc·문서·레지스트리·테스트 이름이 약속한 것)과 다른 동작이 확인됐다 결함 수정
동작은 맞는데 구조 비용이 크다 리팩터링
숫자로 잰 비용이 크다 성능 최적화
leaf·패키지·허용 의존이 바뀐다 구조 변경
테스트가 이름이 말한 것을 증명하지 못한다 테스트 구조 개선

2. 받아야 할 것

  • 리뷰: 범위(전체 / 영역 / 커밋 범위 <base>..<head>와 pathspec), 쓸 심각도 체계(전체 리뷰용인지 확인 리뷰용인지).
  • 수정: 고칠 발견 목록(ID, 위치)과 리뷰 문서 경로.
  • 공통: 기준 커밋, 브랜치, 커밋 허용 여부, 검증할 게이트.
  • 그 발견에 필요한 소유자 결정이 났는지. reference/decisions.md에 없고 brief에도 없으면 그 발견만 멈추고 묻는다.

3. 크기와 사고 순서

  • 보통 중간이다: 확인 리뷰 하나, 수정 묶음 하나.
  • 큼: 전체 리뷰, 구조 변경, 공개 계약을 바꾸는 수정. 큰 일은 1~5단계 결과와 대안을 소유자가 먼저 본다.
  • 이 작업에서 선행 사례는 둘이다: 같은 원인이 남은 다른 자리, 그리고 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대로 별도 세션에 맡긴다.

4. 절차

4.1 리뷰

  1. 범위를 고정한다. 확인 리뷰는 pathspec과 git diff --stat <base>..<head> -- <pathspec> 결과를 문서에 적는다.
  2. 확인 리뷰는 수정 보고의 「새로 가정하는 것」 칸부터 본다. 가정마다 다른 코드·설정·운영에서 참인지 확인한다.
  3. 그다음 수정 diff와, diff가 바꾼 동작의 주변 코드를 읽는다. 확인 리뷰는 저장소 전체가 아니라 그 수정만 본다.
  4. 전체 리뷰는 게이트를 먼저 한 번 돌려 결과를 적고(reference/gates.md), 영역을 나눈다(delegate.md 「나누는 법」).
  5. 의심 결함은 별도 worktree의 임시 테스트(탐침)로 확인한다. 탐침 코드는 고칠 때 옮겨 쓸 수 있게 남기고(소유자 환경에서는 공유 노트 폴더, design-docs conventions/delegation-loop.md 11절), worktree는 지운다.
  6. 발견을 reference/review-criteria.md 양식으로 적는다. 발견마다 증거 수준과 "이번 수정이 만들었나 / 이전부터 있었나"를 적는다.
  7. 리뷰 폴더 README에 색인을 만든다. 발견 ID를 모두 이름으로 적는다. 범위(A~B)와 이어 쓰기(A·07)는 된다. 건수만 쓰지 않는다.
  8. python3 scripts/check-review-index.py docs/reviews/<폴더>를 돌린다. 색인 절이 따로 있으면 --index-heading "<절 제목>"을 붙인다. rc=0이어야 한다.
  9. 판단하지 않은 항목은 「Declined to judge」에 위치와 이유를 적는다. 맡긴 쪽이 다음 묶음에 배정하거나 결정으로 닫는다.

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 2절, 실행 위치는 operate.md).

4.3 리팩터링, 성능, 구조, 테스트 구조

  • 리팩터링: 지킬 동작·타입·실패·진단을 "보존 조건"으로 적는다. 그 조건을 지키는 테스트가 지금 통과하는지 먼저 본다. 리팩터링과 동작 변경을 한 커밋에 섞지 않는다.
  • 복사본을 합칠 때: 정본 하나를 정하고 나머지를 지운다. 못 지우면 이유를 가까운 CLAUDE.md에 적고, 두 벌이 같은지 보는 대조 테스트를 둔다.
  • 성능: 숫자 없이 시작하지 않는다. 기준선 측정 → 원인 좁히기 → 변경 하나 → 같은 조건으로 재측정 → 회귀 테스트로 고정. 조건은 review-criteria.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·스냅숏 같은 생성 파일 제외). 넘으면 확인 리뷰를 나눈다. 묶음 커밋이 따로 있으면 커밋별로, 한 커밋에 여러 영역이 섞였으면 영역 pathspec별로(git diff --shortstat <base>..<head> -- <pathspec>) 나눠 각각 상한 안이 되게 한다.
  • 왜: 지난 수정 라운드에서 추가 줄이 2,000줄 아래면 다음 확인 리뷰 발견이 9건 이하였고, 5,000줄을 넘으면 19건 이상이었다(evidence.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 5절이다.
  • RED를 만들 수 없으면(실 vendor가 없다, 머신에 따라 통과한다) 그 사실과 이유를 보고하고 그 발견만 멈춘다.

8. 보고 형식

README 6절에 더해, 고친 발견마다 아래 칸을 쓴다. 리뷰 README의 처리 표에 그대로 옮길 수 있게 쓴다.

칸 적을 것
발견 고친 발견의 ID와 한 줄 내용(brief와 리뷰 문서에서는 ID를 쓴다)
상태 완료 / 부분(무엇이 남았나) / 못 함(이유)
RED 수정 전 실패한 테스트 이름과 수, 로그 경로
검증 명령, 테스트 수, rc, 로그 경로
처리 내용 바꾼 것, 고치다 새로 찾아 고친 것
새로 가정하는 것 이 변경이 다른 코드·설정·운영에 새로 기대는 것. 확인 리뷰가 여기서 시작한다
정한 기본값 소유자가 확인할 것
범위 밖에서 본 것 위치와 내용. 고치지 않았다

9. 자주 하는 실수

  • 색인을 손으로 옮기다 발견이 빠진다. 색인 검사 스크립트를 돌린다.
  • 보고에 없는 태스크 이름을 적는다. 로그에서 태스크 이름을 grep해 확인한다.
  • 묶음별 검증으로 합친 트리 검증을 대신한다. 라운드 끝 게이트를 따로 돌린다.