문제: 리뷰·결함 수정·리팩터링·성능·구조·테스트 개선마다 시작 조건과 완료 기준이 어디에도 한곳에 없다. 총괄 세션 운영, 리뷰 중 실행 방식, 수정→리뷰 반복의 멈춤 조건은 사용자 지시와 리뷰 README에만 있다. 고른 방법: 01장에 여섯 작업의 시작 조건·단계·산출물·완료 기준을, 09장에 역할, brief, 리뷰 라운드 운영, "게이트는 한 번 돌리고 함께 읽는다", 멈춤 조건(새 High 0·새 P1 0·merge 14개 통과 뒤 그 라운드 Medium·Low 수정), 수정 라운드 운영, 총괄이 자주 한 실수를 적는다. 소유자 환경에 묶인 것은 09장 7절에만 둔다. 위험·한계: 스킬 기록 규칙과 대기 종료 조건 일반화는 [제안]으로 표시했다. 멈춤 기준의 3라운드 상한은 그동안 repo 밖 메모에만 있었다. 검증: 로컬 정적 대조. desktop 검사는 연결 커밋 뒤.
11 KiB
09. 작업 진행 방식
핵심
큰 개선 작업은 총괄 세션 하나와 하위 세션·서브에이전트 여럿으로 나눈다. 총괄은 맡기고, 모으고, 다시 확인하고, 멈출지 정한다. 하위 세션은 맡은 영역 하나를 끝까지 한다.
총괄(오케스트레이터)
├─ 리뷰 라운드: 게이트 1회 실행 → 사본 공유 → 영역 리뷰어 16개 → 실험 목록 → 일괄 실행 → README
├─ 수정 라운드: 영역별 수정 세션(격리 worktree·브랜치) → 통합 브랜치에 합침 → merge 게이트 14개
└─ 멈출 조건 판정 → 마지막 Medium·Low 수정 → 보고
이 장의 규칙은 2026-11-03~05 사용자 지시와 그때 리뷰 README에 남은 운영 기록이 출처다. 이 장이 그 규칙들의 repo 안 정본이다(README 결정 M-9).
1. 역할
| 역할 | 하는 일 | 하지 않는 일 |
|---|---|---|
| 총괄 세션 | 범위·기준 커밋 고정, 게이트 실행, 영역 분할과 brief, 결과 통합, High·새 P1 재확인, 결정 정리, 멈춤 판정, 보고 | 영역 작업을 직접 다 하기. 총괄은 하위 세션에 맡긴다(사용자 지시) |
| 하위 세션 | 맡은 영역의 리뷰 또는 수정. 자기 worktree·브랜치에서 일하고 결과를 보고 | 다른 영역 파일 수정, push·PR, 범위 밖 수정 |
| 서브에이전트 | 한 번에 끝나는 조사·추출·리뷰. 결과를 파일로 남기고 짧게 보고 | 결정, 커밋 |
- 하위 세션이 결정이 필요한 것을 만나면 총괄에 한 번 묻고 기다린다. 스스로 정하지 않는다.
- 짝 백엔드 repo(
clean-architecture-backend-template)는 읽기만 한다. stage·commit·push하지 않는다(사용자 지시). 백엔드에 넘길 것은 리뷰 README 「남은 문제」에 "백엔드에 넘길 것"으로 적는다(1103 README 14.7절).
2. brief 쓰는 법
하위 세션이 아는 것은 brief뿐이다. 다음을 넣는다.
- 목표 한 문장과 끝났다고 볼 조건.
- 기준 커밋·브랜치·작업 위치(worktree 경로).
- 읽을 정본과 지난 기록의 위치(이 매뉴얼 장 번호로).
- 하지 말 것: 리뷰면 코드 수정, 수정이면 범위 밖 파일·push·PR, 공통으로 짝 백엔드 쓰기.
- 실행 위치와 잠금(07장 7절).
- 보고 형식: 바꾼 것, 확인한 것(명령과 결과), 남은 것. 결론을 미리 주지 않는다. 총괄이 만든 변경을 리뷰시킬 때는 코드만 주고 결론은 주지 않는다(1103 README 10.5절 머리말).
3. 리뷰 라운드 운영
- 총괄이 기준 커밋을 고정하고 게이트를 한 번 돌린다(07장 3절).
- 출력과
artifacts/·dist/·test-results/를 읽기 전용 사본으로 뜬다. 4라운드는 desktop의 /tmp/claude-gates/r4/snap/ 에 두었다(1105 README 11.4절). - 영역 리뷰어를 병렬로 띄운다. 영역 표는 가장 최근 README의 것을 다시 쓴다(16개 영역, 1105 README 11.2절).
- 리뷰어는 코드와 사본만으로 판정하고, 더 필요한 실험을 목록으로 낸다(4절).
- 총괄이 실험을 일괄로 돌리고 결과를 영역에 돌려준다.
- 총괄이 High 이상·새 P1을 직접 다시 확인하고 README를 쓴다(02장 6절).
4. 리뷰 중 실행 — 한 번 돌리고 함께 읽는다
사용자 결정이다: 필요할 때만, 묶어서, 실행마다 환경을 되돌린다(1105 README 11.4절, 2026-11-05).
- 게이트는 한 번. 리뷰어마다 같은 빌드·테스트를 다시 돌리지 않는다. 4라운드 처음에 영역 리뷰어 16개가 각자 desktop에서 실행하게 했다가 잠금 줄에 30여 건이 섰고 32건을 취소했다(1105 README 11.5절 첫 행).
- 추가 실험은 목록으로. 항목마다 ID, 명령, env, 시간 상한, 필요하면 변이 패치를 적는다.
- 같은 명령은 한 번만. 두 영역이 같은 변이를 원하면 한 번 돌리고 결과를 함께 쓴다(1105 README 11.4절 셋째 줄).
- 실험마다 작업 폴더를 되돌린다. 항목 앞뒤로 추적 파일을 기준 커밋으로 되돌리고 추적 안 된 파일을 지운다
(
node_modules는 둔다). 4라운드 78항목 모두restore=clean이었다. - 복제본을 늘려 해결하지 않는다. 한 checkout에서 두 실행이 부딪히는 원인은 고정 출력 경로·고정 포트라는 템플릿 결함이다(1105/12-04, 부록 P-06). 복제본을 늘리면 그 결함을 가리고 디스크·설치 비용만 는다.
4라운드의 일괄 실행기와 그 사용법은 같은 세션 그룹의 공유 노트에 있다(07장 7절).
5. 반복과 종료
5.1 반복
리뷰 → 수정 → 다음 라운드 리뷰를 반복한다(2026-11-04 사용자 결정). 라운드 하나의 순서:
- 수정을 통합 브랜치에 합친다(6절).
- merge 게이트 14개를 돌린다(07장 3절).
- 전체 리뷰를 한 번 더 한다. 지난 발견 전부를 ID별로 다시 판정하고 새 발견을 찾는다. 수정 세션의 "고침" 보고를 그대로 믿지 않는다. 1103 조치에서 "고침"으로 적은 것 중 13건이 4라운드에서 "일부"로 정정됐다 (1105 README 3.1절).
- 발견을 고친다.
- 라운드 사이에 새 기능이나 큰 구조 변경을 넣지 않는다. 넣으면 발견 수가 줄어드는지 볼 수 없다.
- 라운드마다 새 발견 수를 High·Medium·Low와 P1로 나눠 앞 라운드와 비교한다(1105 README 4절 표).
5.2 멈출 조건
다음 셋을 모두 채운 라운드에서 멈춘다(2026-11-04 사용자 결정).
- 그 라운드의 새 High 0.
- 그 라운드의 새 P1 0.
- merge 게이트 14개 통과(07장 3절 방법. 고른 스크립트 목록으로 판정하지 않는다).
조건을 채워도 바로 끝내지 않는다. 그 라운드의 Medium·Low를 고치고 멈춘다. 4라운드(1105)는 새 High 0이지만 새 P1이 3건이고 FE-GATE-013이 desktop에서 실패해 조건을 채우지 못했다(1105 README 2.2절, 11.1절).
멈춤 기준은 repo마다 자기 정본을 따른다. 백엔드는 "발견 0까지 확인 리뷰"를 쓴다. 두 기준을 하나로 맞추지 않는다 (2026-11-05 소유자 결정 「각자 유지」, README 결정 M-7).
5.3 남은 문제 0으로 보고한다
- 리뷰 발견은 Low까지 고친다. 보고의 "남은 문제"는 0이어야 한다(사용자 지시).
- 고칠 수 없는 것은 결정 대기로 남긴다. 이유, 선택지, 결정할 사람을 적는다(08장 4절 형식). "나중에", "범위 밖" 같은 이유 없는 이월은 남기지 않는다.
- 개선 제안(결함이 아닌 것)도 열린 채 두지 않는다. 받아서 하거나, 하지 않는 이유를 결정으로 남긴다.
5.4 반복 상한
1103 수정 라운드 뒤로 세 라운드를 더 돌아도 멈출 조건에 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게 보고한다(2026-11-04 사용자 결정). 4라운드(1105)가 그 첫째다. 이 상한은 그동안 repo 밖 작업 메모에만 있었다.
6. 수정 라운드 운영
- 통합 브랜치를 만든다:
fix/maturity-review-<YYYY-MM-DD>(리뷰 날짜). 예:fix/maturity-review-2026-11-03(1103 README 14.1절). - 영역별 수정 세션이 격리 worktree의
fix/r<MMDD>-<이름>브랜치에서 RED 테스트부터 고치고 커밋한다(wave 1). 다른 수정에 기대는 묶음은 그 수정이 합쳐진 뒤 시작한다(wave 2). CHANGELOG·문서는 마지막에 한 세션이 다시 쓴다 (wave 3). - 총괄이 브랜치를
--no-ff로 하나씩 합치고, 합칠 때마다 빠른 게이트를 돌린다(07장 2절). 합친 뒤에만 생긴 실패는 README 「통합에서 생긴 것」에 커밋과 함께 적는다(1103 README 14.3절). - 통합 브랜치에서 merge 게이트 14개를 돌린다.
ci:gate는 첫 실패에서 멈추므로 고칠 때마다 다시 돌리고, 회차별 결과를 표로 남긴다(1103 README 14.5절). - push·PR 본문·최종 보고는 총괄(또는 리뷰를 맡긴 세션)이 한다. 수정 세션은 하지 않는다(1103 README 14절 머리말).
공통 지시(모든 수정 세션의 brief에 넣는다): RED 먼저, 논리적 변경 하나에 커밋 하나, 커밋 규칙, AI 꼬리말 금지,
corepack pnpm, 무거운 실행은 공유 잠금(1103 README 14.1절 셋째 줄).
7. 소유자 환경
이 절은 이 repo 소유자의 도구에 묶인 규칙이다. 복사한 프로젝트는 이 절을 자기 환경으로 바꾼다(README 결정 M-4).
- 세션 도구: Claude Code 데스크톱 앱. 총괄은 하위 세션을 띄우고, 하위 세션은 막힐 때 총괄에 한 번 묻는다.
- 공유 노트: 같은 세션 그룹은 repo 밖 공유 노트 폴더에 큰 발견과 인계 메모를 남긴다. 메시지에 길게 붙이지 않는다. 예: 4라운드 리뷰 위치·일괄 실행기 사용법, FE-GATE-008 원인 조사 두 건.
- 실행 위치와 잠금: 07장 7절.
- 보고: 작업 완료 보고는 "변경 / 확인 / 남은 문제" 세 줄이다. 소유자의 전역 지시가 정본이다(repo 밖).
8. 총괄이 자주 한 실수
리뷰 README의 「오케스트레이터 자신의 실수」 절에서 모았다. 같은 실수를 막는 규칙은 오른쪽 장에 있다.
| 실수 | 결과 | 막는 규칙 |
|---|---|---|
| 게이트 목록을 지난 라운드 목록에서 가져왔다 | 실제 러너에서 항상 실패하는 merge 게이트 둘을 놓쳤다(1103 README 10.5절) | 07장 3절: merge 단계 gateIds로 돌린다 |
| 판정 표를 짝 백엔드 문서만으로 정했다 | 업무 거절이 트랜잭션 전에 난다는 사실을 놓쳐 High를 만들었다(1103/03-01) | 04장 4절: 짝 사실은 코드까지 따라간다 |
| 다운스트림 파일을 열지 않고 이름으로 추정했다 | CHANGELOG에 틀린 이행 안내(1103/14-02) | 08장 4절: 확인하지 않은 것은 "미확인"으로 |
| 지운 코드의 실행 동작만 찾았다 | 지운 검사·테스트가 지키던 동작을 놓쳤다(1103/07-01, 10-04) | 04장 5절: 지울 때는 그 코드가 지키던 것을 찾는다 |
| 영역 리뷰어마다 desktop에서 실행하게 했다 | 잠금 줄 30여 건, 32건 취소(1105 README 11.5절) | 4절 |
verify:documentation을 옆 checkout 없는 임시 worktree에서 pnpm으로 돌렸다 |
pnpm이 재설치를 시도하다 TTY 없음으로 멈춰 결과가 무효(1105 README 11.5절) | 07장 6절 |
제거 드릴을 npm run으로 돌렸다 |
모든 검사가 Unknown command로 실패, 결과를 버렸다(1103 README 10.4절) |
07장 1절: corepack pnpm만 쓴다 |
지금 이해하면 되는 것
- 총괄은 맡기고 모으고 다시 확인한다. 영역 작업은 하위 세션이 한다.
- 리뷰 중 실행은 총괄이 한 번 돌리고 모두가 함께 읽는다. 추가 실험은 목록으로 모아 일괄로 돌린다.
- 새 High 0·새 P1 0·merge 14개 통과면 그 라운드의 Medium·Low를 고치고 멈춘다. 못 고친 것은 결정 대기로 남긴다.