문제: 07장은 desktop 빌드를 "겹치지 않게"라고만 적고 잠금 파일을 정하지 않았다. 짝 프론트도 같은 desktop에서 돌려 부하와 포트(4173·4174)가 겹칠 수 있다. 또 두 repo 매뉴얼은 장 구성이 같은데, 리뷰 반복 종료 조건은 소유자가 "각자 유지"로 정해 서로 다르다. 이 차이가 매뉴얼에 없으면 같은 뼈대를 보고 같은 조건으로 오해한다. 방법: 07장 6절 절차와 규칙에 `flock /tmp/claude-gates/heavy.lock`을 넣고 한 줄 명령을 적는다(총괄 세션 지시). 08장 색인에 "두 repo의 종료 조건"과 "desktop 공유 잠금" 행을 더하고, 누가 칸에 "총괄 지시"·"정책" 뜻을 적는다. README의 프론트 뼈대 절과 09장 5절에 이 조건만 의도적으로 다르다고 적는다. 검증: 인용 경로·ID·링크·절 번호 대조 스크립트를 다시 돌렸다(새 불일치 없음). 문서 대조 lane은 push 뒤 desktop에서 잠금 아래 다시 돌린다.
9.9 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에서 돌렸다
(
1103README 17.1·17.2절). - 총괄은 High·Important 이상을 코드에서 직접 다시 확인한다(
1101README 2절). - 총괄은 보고를 믿지 않고 확인한다. 보고는 E0 증거다(02장 4절).
2. 나누는 법
- 영역 분할은 최근 리뷰의 영역 표를 다시 쓴다. 전체 리뷰는
1101README 9절의 9영역, 재리뷰는1103README 2절의 7영역, 확인 리뷰는 4영역(1103/round6/). - 두 묶음이 같은 파일을 건드리지 않게 나눈다. 겹치면 합칠 때 손으로 풀어야 한다. 2라운드는 묶음 사이 충돌이 많아 한 묶음을
처음부터 다시 시켰다(
1101README 14.1절 r2-06 "10개 파일 충돌로 baseline2 위에서 다시 작업"). - 묶음마다 그 시점의 메인 상태에서 시작한다. 3라운드가 2라운드보다 충돌이 적었던 이유다(
1101README 16.1절). - 전 leaf의 import를 바꾸는 묶음은 마지막에 혼자 한다(
1101README 15.1절 r3-G). - 한 묶음을 너무 크게 만들지 않는다. 알림·파일 서버를 한 묶음으로 묶었다가 마감 안에 검증 보고가 오지 않아 합치지 못했다
(
1101README 14.3절 r2-05a). 그 묶음은 다음 라운드에 다시 올려 합쳤다(1101README 16절 r3-a). - 같은 결함을 두 영역이 보면 한 묶음에만 배정한다. 같은 문장을 두 리뷰가 적은 것은 한 번 고쳤다(
1103README 17절 "RR6-01-07과 RR6-02-03은 같은 runbook 문장이라 한 번 고쳤다").
3. brief에 넣을 것
brief는 하위 단위가 받는 유일한 맥락이다. 빠뜨린 것은 하위 단위가 모른다.
- 목표와 완료 기준. 무엇이 끝나면 끝인가(01장의 해당 작업 완료 기준).
- 기준 커밋·브랜치·worktree. 어디서 시작하고 어디에 커밋하나.
- 범위. pathspec과 발견 ID 목록. 범위 밖 발견은 "고치지 말고 보고"(
1103README 12절 "맡은 Minor 밖은 고치지 않고 보고만 하게 했다"). - 이미 정한 결정. 08장 색인의 해당 행과 원문 위치. "다시 묻지 말 것".
- 쓸 스킬. 01장 표에서. 리뷰면 리뷰어 템플릿과 영역 스킬(
1103README 머리말). - 심각도 기준(리뷰면). 02장 3절 정의를 그대로 붙인다(
1103README 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절 「범위」).
종료 조건 — 모두 만족해야 끝난다.
- 마지막 확인 리뷰의 발견이 심각도와 상관없이 0이다.
- 열린 「Declined to judge」 항목이 없다. 판단하지 않은 항목은 총괄이 다음 묶음에 배정하거나 결정으로 닫았다.
- 합친 트리에서 07장 3절 전체 묶음이 통과했다.
- 리뷰 README의 "남음" 항목이 0이다. 결정으로 닫은 것은 결정 위치가 적혀 있다.
예전 멈춤 기준("새 Important 0이면 멈춤", "Minor는 기록만")은 소유자가 거뒀다(1103 README 16절, 08장 1절).
이 종료 조건은 이 repo의 것이다. 짝 프론트 repo는 다른 종료 조건을 쓴다. 소유자가 두 repo의 조건을 "각자 유지"로 정했다 (08장 1절 「두 repo의 종료 조건」). 장 구성은 같고 이 조건만 다르다.
코드로 고칠 수 없는 것: 소유자 결정이 필요한 것만 남을 수 있다. 그것은 근거와 권하는 안을 붙여 질문으로 보고한다. 질문이 답을 받으면 다시 고치기로 돌아간다.
종료 조건을 미리 정한다: 라운드를 시작할 때 그 라운드의 멈춤 조건을 README에 적는다(1103 README 9.1절 끝 문단처럼).
이 매뉴얼의 종료 조건과 다르면 이 매뉴얼을 따른다.
6. 소유자 환경 — 세션 분업
이 절은 이 repo 소유자의 작업 도구에 묶인 규칙이다. 파생 프로젝트는 이 절만 자기 환경으로 바꾼다(README 결정 M-6). 출처: 2026-11-05 총괄 세션 brief(README 결정 M-9).
- 총괄 세션은 지휘만 한다. 하위 작업 단위는 Claude 데스크톱 앱의 하위 세션(별도 세션, 사용자가 열어 보고 멈출 수 있다)으로 띄운다. 세션 안의 하위 에이전트(subagent)로 돌리지 않는다.
- 하위 세션 안에서 다시 하위 에이전트를 띄우지 않는다. 넓은 조사는 그 세션이 직접 나눠 읽는다. 지난 라운드도 사용량 한도
때문에 하위 에이전트 없이 진행했다(
1101README 16절 "하위 에이전트는 쓰지 않았다(지난 라운드 사용량 한도)",1103README 6절 "하위 에이전트 없음"). - 세션마다 자기 worktree와 브랜치를 쓴다. 같은 checkout을 두 세션이 동시에 쓰지 않는다. desktop checkout은 예외로 함께 쓰므로 07장 6절 절차를 따른다.
- 세션끼리는 공유 노트 폴더로 큰 결과를 넘긴다. 탐침 코드와 실행 로그처럼 메시지에 넣기 큰 것은 노트 폴더에 두고 위치만
보고한다(
1103/round6/01-core-inbound.md"탐침 코드와 결과 파일은 공유 노트 폴더rr6-01-probes/에"). - 짝 프론트 repo의 일은 프론트 쪽 총괄 세션을 거친다. 계약 변경은 인계 문서로 넘긴다(
1101README 16.3절 "프론트 인계").
지금 이해하면 되는 것
- 총괄은 나누고·지시하고·대조하고·기록한다. 일은 하위 단위가 자기 worktree에서 한다.
- brief는 하위 단위의 유일한 맥락이다. 결정·범위·검증 위치·보고 형식을 빠뜨리지 않는다.
- 확인 리뷰는 수정 diff만 보고, 발견 0 + Declined 0 + 전체 게이트 통과 + "남음" 0일 때 끝난다.