# 09. 작업 진행 방식 ## 핵심 큰 개선 작업은 **총괄 세션 하나와 하위 세션·서브에이전트 여럿**으로 나눈다. 총괄은 맡기고, 모으고, 다시 확인하고, 멈출지 정한다. 하위 세션은 맡은 영역 하나를 끝까지 한다. ```text 총괄(오케스트레이터) ├─ 리뷰 라운드: 게이트 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뿐이다. 다음을 넣는다. 1. 목표 한 문장과 끝났다고 볼 조건. 2. 기준 커밋·브랜치·작업 위치(worktree 경로). 3. 읽을 정본과 지난 기록의 위치(이 매뉴얼 장 번호로). 4. 하지 말 것: 리뷰면 코드 수정, 수정이면 범위 밖 파일·push·PR, 공통으로 짝 백엔드 쓰기. 5. 실행 위치와 잠금(07장 7절). 6. 보고 형식: 바꾼 것, 확인한 것(명령과 결과), 남은 것. 결론을 미리 주지 않는다. 총괄이 만든 변경을 리뷰시킬 때는 코드만 주고 결론은 주지 않는다(1103 README 10.5절 머리말). ## 3. 리뷰 라운드 운영 1. 총괄이 기준 커밋을 고정하고 게이트를 **한 번** 돌린다(07장 3절). 2. 출력과 `artifacts/`·`dist/`·`test-results/`를 읽기 전용 사본으로 뜬다. 4라운드는 desktop의 /tmp/claude-gates/r4/snap/ 에 두었다(1105 README 11.4절). 3. 영역 리뷰어를 병렬로 띄운다. 영역 표는 가장 최근 README의 것을 다시 쓴다(16개 영역, 1105 README 11.2절). 4. 리뷰어는 코드와 사본만으로 판정하고, 더 필요한 실험을 목록으로 낸다(4절). 5. 총괄이 실험을 일괄로 돌리고 결과를 영역에 돌려준다. 6. 총괄이 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 사용자 결정). 라운드 하나의 순서: 1. 수정을 통합 브랜치에 합친다(6절). 2. merge 게이트 14개를 돌린다(07장 3절). 3. 전체 리뷰를 한 번 더 한다. 지난 발견 전부를 ID별로 다시 판정하고 새 발견을 찾는다. 수정 세션의 "고침" 보고를 그대로 믿지 않는다. 1103 조치에서 "고침"으로 적은 것 중 13건이 4라운드에서 "일부"로 정정됐다 (1105 README 3.1절). 4. 발견을 고친다. - 라운드 사이에 새 기능이나 큰 구조 변경을 넣지 않는다. 넣으면 발견 수가 줄어드는지 볼 수 없다. - 라운드마다 새 발견 수를 High·Medium·Low와 P1로 나눠 앞 라운드와 비교한다(1105 README 4절 표). ### 5.2 멈출 조건 다음 셋을 모두 채운 라운드에서 멈춘다(2026-11-04 사용자 결정). 1. 그 라운드의 **새 High 0**. 2. 그 라운드의 **새 P1 0**. 3. **merge 게이트 14개 통과**(07장 3절 방법. 고른 스크립트 목록으로 판정하지 않는다). 조건을 채워도 바로 끝내지 않는다. **그 라운드의 Medium·Low를 고치고** 멈춘다. 4라운드(1105)는 새 High 0이지만 새 P1이 3건이고 FE-GATE-013이 desktop에서 실패해 조건을 채우지 못했다(1105 README 2.2절, 11.1절). 멈춤 기준은 repo마다 자기 정본을 따른다. 두 기준을 하나로 맞추지 않는다(2026-11-05 소유자 결정 「각자 유지」, README 결정 M-7, 08장 표 O-12). - 백엔드와의 차이는 **마지막 수정이 확인 리뷰를 받는가**다. 백엔드는 리뷰 → 수정 → 확인 리뷰를 발견이 심각도와 상관없이 0이 될 때까지 돌아, 마지막 라운드에서 고친 Medium·Low도 확인 리뷰를 받는다. 프론트는 멈출 조건을 채운 라운드의 Medium·Low를 고치고 멈추므로, 그 마지막 수정은 다음 리뷰를 받지 않는다. - 그래서 마지막 수정이 새 결함을 만들면(부록 P-26) 리뷰가 아니라 그 수정의 RED·GREEN 테스트와 merge 게이트 14개만이 잡는다. 마지막 수정도 01장 2절 절차(특히 5단계 "템플릿 원래 상태 밖에서도 확인")와 07장 3절 merge 판정을 그대로 거친다. ### 5.3 남은 문제 0으로 보고한다 - 리뷰 발견은 Low까지 고친다. 보고의 "남은 문제"는 0이어야 한다(사용자 지시). - 수정 결과를 보고할 때 「고침」은 확정이 아니다. 다음 리뷰가 ID별로 다시 판정한다(5.1절 3단계). 보고서에도 "다음 리뷰에서 재판정"이라고 적는다. 1103 조치의 「고침」 13건이 4라운드에서 「일부」로 정정됐다(2026-11-05 사용자 지시, 총괄 세션 전달). - 고칠 수 없는 것은 **결정 대기**로 남긴다. 이유, 선택지, 결정할 사람을 적는다(08장 4절 형식). "나중에", "범위 밖" 같은 이유 없는 이월은 남기지 않는다. - 개선 제안(결함이 아닌 것)도 열린 채 두지 않는다. 받아서 하거나, 하지 않는 이유를 결정으로 남긴다. ### 5.4 반복 상한 1103 수정 라운드 뒤로 세 라운드를 더 돌아도 멈출 조건에 닿지 않으면 멈추고, 왜 수렴하지 않는지 소유자에게 보고한다(2026-11-04 사용자 결정). 4라운드(1105)가 그 첫째다. 이 상한은 그동안 repo 밖 작업 메모에만 있었다. ## 6. 수정 라운드 운영 1. 통합 브랜치를 만든다: `fix/maturity-review-`(리뷰 날짜). 예: `fix/maturity-review-2026-11-03` (1103 README 14.1절). 2. 영역별 수정 세션이 격리 worktree의 `fix/r-<이름>` 브랜치에서 RED 테스트부터 고치고 커밋한다(wave 1). 다른 수정에 기대는 묶음은 그 수정이 합쳐진 뒤 시작한다(wave 2). CHANGELOG·문서는 마지막에 한 세션이 다시 쓴다 (wave 3). 3. 총괄이 브랜치를 `--no-ff`로 하나씩 합치고, 합칠 때마다 빠른 게이트를 돌린다(07장 2절). 합친 뒤에만 생긴 실패는 README 「통합에서 생긴 것」에 커밋과 함께 적는다(1103 README 14.3절). 4. 통합 브랜치에서 merge 게이트 14개를 돌린다. `ci:gate`는 첫 실패에서 멈추므로 고칠 때마다 다시 돌리고, 회차별 결과를 표로 남긴다(1103 README 14.5절). 5. push·PR 본문·최종 보고는 총괄(또는 리뷰를 맡긴 세션)이 한다. 수정 세션은 하지 않는다(1103 README 14절 머리말). 6. **큰 라운드는 작은 PR로 나눈다.** 라운드 전체를 PR 하나로 올리지 않는다. 자기완결적인 변경 하나(예: 영역 수정 브랜치 하나)를 PR 하나로 낸다. 크기는 대략 100줄이 적당하고 1,000줄이면 너무 크다. 리팩터링과 동작 변경은 PR을 나눈다. 기계적으로 만든 큰 변경은 크기 예외로 두고 만든 명령과 기준 커밋을 적는다(커밋 규칙 5.1절). 소유자가 PR을 직접 merge한다(2026-11-05 사용자 지시, 총괄 세션 전달). 직전 라운드는 발견·결정 24건을 Gitea PR 하나(4번, main 커밋 `409d72e`)로 올렸다. 공통 지시(모든 수정 세션의 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를 고치고 멈춘다. 못 고친 것은 결정 대기로 남긴다.