Files
clean-architecture-backend-…/docs/improvement/09-working-method.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

9.7 KiB

09. 작업 진행 방식

핵심

큰 개선 작업은 총괄 하나와 여러 하위 작업 단위로 나눠 한다. 총괄은 범위를 정하고, 나누고, 지시하고(brief), 결과를 대조하고, 기록한다. 리뷰·수정·검증 같은 실제 작업은 하위 단위가 자기 worktree에서 한다. 리뷰 → 수정 → 확인 리뷰를 발견이 0이 될 때까지 반복한다.

총괄
 ├─ 범위·기준 커밋 고정, 이전 결정 읽기(08장)
 ├─ 영역·묶음 나누기(2절) ──> brief 쓰기(3절)
 │        ┌──────────────┬──────────────┬──────────────┐
 │        v              v              v              v
 │     하위 A          하위 B          하위 C          하위 D      (각자 worktree·브랜치, RED→GREEN, 영역 검증)
 │        └──────┬───────┴──────────────┴──────────────┘
 │               v
 ├─ 보고를 diff·실행 기록과 대조(4절) ──> 합치기 + 전체 게이트(07장 3절)
 ├─ 리뷰 README에 처리 표·결정·게이트 기록
 └─ 확인 리뷰(수정 diff만) ──> 발견 0? ── 아니면 다시 나누기
                                   └─ 0이면 보고(5절)

하위 작업 단위를 무엇으로 띄우는지는 환경에 묶인 규칙이라 6절 「소유자 환경」에 따로 둔다.

1. 역할

총괄이 한다 하위 단위가 한다
범위·기준 커밋·영역 분할 맡은 영역의 리뷰, 또는 맡은 발견의 수정
brief 작성, 결정 색인 연결 RED → GREEN, 같은 원인의 다른 자리 찾기, 문서 동기화
소유자에게 결정 묻기(근거와 권하는 안을 붙여) 영역 검증(leaf check, 관련 lane)
보고를 diff·실행 기록과 대조 처리 표 한 행 형식의 보고
리뷰 README 기록, 소유자 보고 범위 밖 발견은 고치지 않고 보고
  • 합치기와 전체 게이트도 하위 단위에 맡길 수 있다. r10 수정의 전체 게이트는 별도 작업 단위가 desktop에서 돌렸다 (1103 README 17.1·17.2절).
  • 총괄은 High·Important 이상을 코드에서 직접 다시 확인한다(1101 README 2절).
  • 총괄은 보고를 믿지 않고 확인한다. 보고는 E0 증거다(02장 4절).

2. 나누는 법

  • 영역 분할은 최근 리뷰의 영역 표를 다시 쓴다. 전체 리뷰는 1101 README 9절의 9영역, 재리뷰는 1103 README 2절의 7영역, 확인 리뷰는 4영역(1103/round6/).
  • 두 묶음이 같은 파일을 건드리지 않게 나눈다. 겹치면 합칠 때 손으로 풀어야 한다. 2라운드는 묶음 사이 충돌이 많아 한 묶음을 처음부터 다시 시켰다(1101 README 14.1절 r2-06 "10개 파일 충돌로 baseline2 위에서 다시 작업").
  • 묶음마다 그 시점의 메인 상태에서 시작한다. 3라운드가 2라운드보다 충돌이 적었던 이유다(1101 README 16.1절).
  • 전 leaf의 import를 바꾸는 묶음은 마지막에 혼자 한다(1101 README 15.1절 r3-G).
  • 한 묶음을 너무 크게 만들지 않는다. 알림·파일 서버를 한 묶음으로 묶었다가 마감 안에 검증 보고가 오지 않아 합치지 못했다 (1101 README 14.3절 r2-05a). 그 묶음은 다음 라운드에 다시 올려 합쳤다(1101 README 16절 r3-a).
  • 같은 결함을 두 영역이 보면 한 묶음에만 배정한다. 같은 문장을 두 리뷰가 적은 것은 한 번 고쳤다(1103 README 17절 "RR6-01-07과 RR6-02-03은 같은 runbook 문장이라 한 번 고쳤다").

3. brief에 넣을 것

brief는 하위 단위가 받는 유일한 맥락이다. 빠뜨린 것은 하위 단위가 모른다.

  • 목표와 완료 기준. 무엇이 끝나면 끝인가(01장의 해당 작업 완료 기준).
  • 기준 커밋·브랜치·worktree. 어디서 시작하고 어디에 커밋하나.
  • 범위. pathspec과 발견 ID 목록. 범위 밖 발견은 "고치지 말고 보고"(1103 README 12절 "맡은 Minor 밖은 고치지 않고 보고만 하게 했다").
  • 이미 정한 결정. 08장 색인의 해당 행과 원문 위치. "다시 묻지 말 것".
  • 쓸 스킬. 01장 표에서. 리뷰면 리뷰어 템플릿과 영역 스킬(1103 README 머리말).
  • 심각도 기준(리뷰면). 02장 3절 정의를 그대로 붙인다(1103 README 11절 "심각도 기준을 지침에 적었다").
  • 검증 위치와 명령. 07장 6절 「소유자 환경」, 돌릴 게이트.
  • 하지 말 것. 리뷰는 코드 수정 금지, 다른 브랜치 push 금지, PR·병합 금지, 하위의 하위 위임 금지(환경에 따라).
  • 커밋 허용 여부와 규칙. 08장 4절.
  • 보고 형식. 4절.
  • 막혔을 때. 소유자만 정할 수 있는 것은 근거와 권하는 안을 붙여 묻는다.

4. 보고 형식

하위 단위 → 총괄: 리뷰 README 처리 표의 한 행으로 바로 옮길 수 있게 쓴다(1101 README 13절, 1103 README 6·10·12·16·17절 표).

칸 적을 것
묶음·발견 ID r10-02, RR6-02-01~05
상태 완료 / 부분(무엇이 남았나) / 못 함(이유)
검증 명령과 테스트 수. 예: "redisContainerContractTest 78, PG 계약 31"
RED 수정 전 실패한 테스트 이름과 수
처리 내용 무엇을 바꿨나, 고치다 새로 찾아 고친 것
결정·남은 것 정한 기본값(소유자 확인 대상), 남은 것

함께 줄 것: 브랜치와 커밋 sha, 실행 로그 위치, 범위 밖에서 본 결함.

총괄 → 소유자: 바꾼 것 · 확인한 것(게이트·rc·커밋) · 남은 문제. 남은 문제를 숨기지 않는다(AGENTS.md 「작업 보고 규칙」). 소유자가 이미 아는 외부 일(PR 병합, CI runner 켜기)은 「소유자 일」로 한 번만 적고 남은 문제와 섞지 않는다(1103 README 13.1절 "소유자 일").

5. 리뷰 → 수정 반복과 종료 조건

왜 반복하나: 수정이 새 결함을 만든다. 1차 재리뷰는 원래 리뷰의 수정에서 Important 27건을 찾았고(1103 README 1절), 그 수정을 다시 본 2차 재리뷰도 새 Important를 찾았다(1103 README 9절 표 "이번 라운드가 새로 만든 Important"). round6은 r9 수정의 회귀를 찾았다(1103/RR6-01-01).

확인 리뷰의 범위: 저장소 전체가 아니라 그 수정 커밋만 본다. 전 영역은 이미 봤고, 남은 위험은 "수정이 새 결함을 만든다"이기 때문이다(1103 README 9절). 수정 diff가 건드린 동작의 주변 코드는 함께 읽는다(02장 8.2절 「범위」).

종료 조건 — 모두 만족해야 끝난다.

  1. 마지막 확인 리뷰의 발견이 심각도와 상관없이 0이다.
  2. 열린 「Declined to judge」 항목이 없다. 판단하지 않은 항목은 총괄이 다음 묶음에 배정하거나 결정으로 닫았다.
  3. 합친 트리에서 07장 3절 전체 묶음이 통과했다.
  4. 리뷰 README의 "남음" 항목이 0이다. 결정으로 닫은 것은 결정 위치가 적혀 있다.

예전 멈춤 기준("새 Important 0이면 멈춤", "Minor는 기록만")은 소유자가 거뒀다(1103 README 16절, 08장 1절).

코드로 고칠 수 없는 것: 소유자 결정이 필요한 것만 남을 수 있다. 그것은 근거와 권하는 안을 붙여 질문으로 보고한다. 질문이 답을 받으면 다시 고치기로 돌아간다.

종료 조건을 미리 정한다: 라운드를 시작할 때 그 라운드의 멈춤 조건을 README에 적는다(1103 README 9.1절 끝 문단처럼). 이 매뉴얼의 종료 조건과 다르면 이 매뉴얼을 따른다.

6. 소유자 환경 — 세션 분업

이 절은 이 repo 소유자의 작업 도구에 묶인 규칙이다. 파생 프로젝트는 이 절만 자기 환경으로 바꾼다(README 결정 M-6). 출처: 2026-11-05 총괄 세션 brief(README 결정 M-9).

  • 총괄 세션은 지휘만 한다. 하위 작업 단위는 Claude 데스크톱 앱의 하위 세션(별도 세션, 사용자가 열어 보고 멈출 수 있다)으로 띄운다. 세션 안의 하위 에이전트(subagent)로 돌리지 않는다.
  • 하위 세션 안에서 다시 하위 에이전트를 띄우지 않는다. 넓은 조사는 그 세션이 직접 나눠 읽는다. 지난 라운드도 사용량 한도 때문에 하위 에이전트 없이 진행했다(1101 README 16절 "하위 에이전트는 쓰지 않았다(지난 라운드 사용량 한도)", 1103 README 6절 "하위 에이전트 없음").
  • 세션마다 자기 worktree와 브랜치를 쓴다. 같은 checkout을 두 세션이 동시에 쓰지 않는다. desktop checkout은 예외로 함께 쓰므로 07장 6절 절차를 따른다.
  • 세션끼리는 공유 노트 폴더로 큰 결과를 넘긴다. 탐침 코드와 실행 로그처럼 메시지에 넣기 큰 것은 노트 폴더에 두고 위치만 보고한다(1103/round6/01-core-inbound.md "탐침 코드와 결과 파일은 공유 노트 폴더 rr6-01-probes/에").
  • 짝 프론트 repo의 일은 프론트 쪽 총괄 세션을 거친다. 계약 변경은 인계 문서로 넘긴다(1101 README 16.3절 "프론트 인계").

지금 이해하면 되는 것

  • 총괄은 나누고·지시하고·대조하고·기록한다. 일은 하위 단위가 자기 worktree에서 한다.
  • brief는 하위 단위의 유일한 맥락이다. 결정·범위·검증 위치·보고 형식을 빠뜨리지 않는다.
  • 확인 리뷰는 수정 diff만 보고, 발견 0 + Declined 0 + 전체 게이트 통과 + "남음" 0일 때 끝난다.