# 총괄 — 큰 일을 나눠 다른 세션에 맡긴다 총괄 세션이 일을 나누고, brief를 쓰고, 결과를 대조하고, 합치는 절차다. 공용 절차(brief 양식, 보고 양식, 대조, 교훈 정리, 장부, 지표)의 정본은 design-docs `conventions/delegation-loop.md`다. 이 playbook은 그것을 다시 쓰지 않고, 이 repo의 일을 나누는 법만 더한다. ```text 총괄 ├─ 리뷰 라운드: 게이트 1회 → 사본 공유 → 영역 리뷰어 → 실험 목록 → 일괄 실행 → README ├─ 수정 라운드: 영역별 수정 세션(자기 worktree·브랜치) → 통합 브랜치 → merge 단계 └─ 멈춤 판정 → 마지막 Medium·Low 수정 → 보고 ``` ## 1. 언제 쓰나 - 일이 커서 여러 세션으로 나눠야 할 때: 전체 리뷰, 영역별 수정 묶음, 리뷰와 수정의 반복, 여러 playbook에 걸친 일. - 세션 하나가 끝까지 할 수 있는 일이면 이 playbook이 아니다. 그 일의 playbook을 쓴다. - 맡은 쪽(하위 세션)은 이 playbook이 아니라 brief가 가리킨 playbook을 따른다. ## 2. 받아야 할 것 - 소유자의 목표와 이미 정한 결정. 큰 일이면 소유자가 계획을 검토한 시각. - 결과가 올라갈 브랜치와 그 최신 커밋(기준 커밋). - 커밋 허용과 자기 브랜치 push 허용(따로 적는다). push 없이도 desktop 검증은 된다(`scripts/verify.sh`가 패치로 옮긴다). main 병합·main push는 소유자가 한다. - 마감과 보고 받을 방법. ## 3. 크기와 사고 순서 - 크기는 총괄이 정해 brief에 적는다. 정의는 design-docs `conventions/work-thinking-order.md` 2절이다. 큰 일은 하위 세션이 1~5단계와 대안 비교까지만 하고 멈추게 쓴다. 소유자 검토 뒤 만들기를 다시 맡긴다. - 총괄 자신의 선행 사례는 지난 라운드의 나누는 법이다: 가장 최근 리뷰 README의 영역 표, 「조치」 절, 「오케스트레이터 자신의 실수」 절. - 스킬: `delegate`(소유자 환경의 실행판)가 있으면 쓴다. 정본과 다르면 정본이 맞다. ## 4. 절차 ### 4.1 맡기고 닫는 순서 design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 → 나누기(4.2절) → 기준 커밋 → brief → 하위 세션 띄우기 → 보고 대조 → 합치기 → 교훈 정리 → 장부 한 줄 → 소유자 보고. 이 repo에서 더할 것: - 하위 세션은 착수 보고(이해한 것, 모호한 점과 고른 가정, 예측)를 공유 노트에 쓰고 기다리지 않는다. 예측과 실측은 그 세션이 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다. - brief에 넣을 것: 목표 한 문장과 끝났다고 볼 조건, 기준 커밋·브랜치·worktree, 읽을 정본과 지난 기록의 위치, 하지 말 것(리뷰면 코드 수정, 수정이면 범위 밖 파일·push·PR, 공통으로 짝 백엔드 쓰기), 실행 위치(`scripts/verify.sh`, [operate.md](operate.md) 4.1절), 보고 형식. - 「이미 아는 것」에는 [reference/decisions.md](reference/decisions.md)의 결정을 **내용으로** 옮긴다. 번호만 쓰지 않는다. - 결론을 미리 주지 않는다. 총괄이 만든 변경을 리뷰시킬 때는 코드만 주고 결론은 주지 않는다. - 수정 묶음 brief에는 공통 지시를 넣는다: RED 먼저, 논리 변경 하나에 커밋 하나, 커밋 규칙, AI 꼬리말 금지, `corepack pnpm`, 무거운 실행은 desktop 공유 잠금 아래. 보고의 「새로 가정하는 것」 칸을 요구한다. - 하위 세션이 결정이 필요한 것을 만나면 총괄에 한 번 묻고 기다린다. 스스로 정하지 않는다. - 대조할 때: 보고의 명령·테스트 수를 desktop 로그(`/tmp/claude-gates/<로그 이름>/summary.txt`)에서 찾는다. High 이상과 새 P1은 총괄이 코드에서 직접 다시 확인한다. - 수정 결과의 "고침"을 그대로 믿지 않는다. 다음 리뷰가 ID별로 다시 판정한다. - 교훈을 보낼 곳: 그 playbook의 「자주 하는 실수」, 코드 결함 모양은 [reference/defect-patterns.md](reference/defect-patterns.md), 거짓 통과는 [reference/gates.md](reference/gates.md) 6절, 근거는 [evidence.md](evidence.md). ### 4.2 나누는 법 — 이 repo 영역은 가장 최근 리뷰 README의 영역 표(16개)를 다시 쓴다. 영역 하나에 리뷰어 하나다. | 영역 묶음 | 경로 | | --- | --- | | adapters(6개 영역) | `src/adapters/<그룹>/`: browser-transfer, browser-files·cache·cross-context, http·state, realtime, storage·kernel, service worker·push | | contracts, presentation, app core | `src/contracts/`, `src/presentation/`, `src/bootstrap/`·`src/features/`·`src/platform/` | | 테스트(2개 영역) | `tests/` 빠른 계층, 브라우저·릴리스·규모 | | guardrails·CI, build·release | `scripts/`, `config/ci/`, `.gitea/`, 공급망·release 경로 | | 문서, 성능, 구조 | `docs/`·`README.md`, 예산과 실측, 폴더 구조·기능 개발 패턴 | **리뷰 중 실행 — 한 번 돌리고 함께 읽는다**(소유자 결정 2026-11-05). - 게이트는 총괄이 한 번 돌린다. 리뷰어마다 같은 빌드·테스트를 다시 돌리지 않는다. 영역 리뷰어 16개가 각자 desktop에서 돌려 잠금 줄에 30여 건이 서고 32건을 취소한 일이 있다. - 추가 실험은 목록으로 모은다. 항목마다 ID, 명령, env, 시간 상한, 필요하면 변이 패치. 같은 명령은 한 번만 돌리고 결과를 함께 쓴다. - 실험마다 작업 폴더를 되돌린다. 항목 앞뒤로 추적 파일을 기준 커밋으로 되돌리고 추적 안 된 파일을 지운다(`node_modules`는 둔다). - 작업 폴더 복제본을 늘려 해결하지 않는다. 한 checkout에서 두 실행이 부딪히는 원인은 고정 출력 경로·고정 포트라는 템플릿 결함이다. 복제본은 그 결함을 가린다. 두 세션이 동시에 만지면 손으로 풀어야 하는 파일이다. 한 세션만 맡기거나, 총괄이 합칠 때 직접 고친다. | 파일 | 왜 | | --- | --- | | `CHANGELOG.md` | 묶음마다 미출시 절의 같은 줄 근처를 고친다. 마지막에 한 세션이 다시 쓴다 | | `docs/reviews/<폴더>/README.md` | 범위·판정표·요약·색인·조치는 총괄이 쓴다 | | `docs/reviews/adapters/INVENTORY.md`, `.dependency-cruiser.json` | adapter·규칙 하나가 모든 그룹에 걸린다 | | `config/ci/gates.json`, `.gitea/workflows/*`, `package.json`, `pnpm-lock.yaml` | 단계 검사·생성 workflow·lockfile 전체가 바뀐다 | | `config/performance/budgets.json`, 초기 JS 기준선 기록 | 묶음마다 맞아도 합친 트리에서 낡는다. 합친 끝에서 다시 잰다 | | 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/`, `scripts/hooks/`, `scripts/verify.sh` | 모든 세션이 읽거나 모든 세션에 걸린다 | 나눌 때 지킬 것: 두 묶음이 같은 파일을 건드리지 않게 나눈다. 묶음마다 그 시점 최신 기준에서 시작한다. 같은 결함을 두 영역이 보면 한 묶음에만 배정한다. 합칠 때 충돌 해결 밖에서 새로 고칠 것이 생기면 병합 커밋에 넣지 않고 따로 커밋한다. ### 4.3 소유자 환경 하위 세션을 띄우는 법, 보고가 총괄에게 전달되는 길, 공유 노트 폴더, 짝 백엔드 일의 경로 같은 규칙은 design-docs `conventions/delegation-loop.md` 11절 한 곳에 있다. 이 repo에서 더할 것: - 나누는 기준(소유자 결정 2026-11-07): - 파일을 바꾸는 위임, 소유자가 열어 보고 멈출 수 있어야 하는 일은 하위 세션(이 playbook)이다. - 결과만 받는 일(넓은 검색, 구조 리뷰 `arch-reviewer`, desktop에서 앱을 띄워 보는 확인 `verify-app`, 단순화 제안 `code-simplifier`, 영역 리뷰처럼 문서를 커밋하지 않는 리뷰)은 서브에이전트(정의 `.claude/agents/`)다. 서브에이전트는 파일을 고치지 않는다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. - pnpm·게이트·브라우저는 누가 돌려도 desktop에서다(`scripts/verify.sh`). - 짝 백엔드 repo는 읽기만 한다. stage·commit·push하지 않는다. - 공유 노트: 같은 세션 그룹은 repo 밖 공유 노트 폴더에 큰 발견과 인계 메모를 남긴다. 메시지에 길게 붙이지 않는다. 하위 세션은 다른 노트를 먼저 읽는다. - 이 절은 소유자의 도구에 묶인 규칙이다. 복사한 프로젝트는 이 절과 [operate.md](operate.md) 4.1절만 자기 환경으로 바꾼다. ## 5. 완료 기준 - 하위 세션마다 brief가 양식대로이고 자리표시자가 없다. - 보고를 diff·커밋·로그와 대조했고 불일치를 셌다. - 합친 트리에서 merge 단계가 통과했다(desktop 로그). - 리뷰·수정 반복이면 [improve.md](improve.md) 4.5절 멈춤 기준이 모두 참이다. - 교훈 정리와 장부 한 줄을 끝냈다. 소유자 보고에 변경 / 확인(명령·결과·커밋) / 남은 문제가 있다. ## 6. 하지 말 것 - 하위 세션의 일을 대신 하지 않는다. 대조에 필요한 읽기와 확인만 직접 한다. - 보고를 그대로 믿지 않는다. 같은 파일을 두 세션에 맡기지 않는다. - 하위 세션에 main 병합·main push, force push, 다른 브랜치 push를 허용하지 않는다. - 영역 리뷰어마다 desktop에서 게이트를 돌리게 하지 않는다(4.2절). ## 7. 막혔을 때 - 소유자만 정할 수 있는 것은 근거와 권하는 안을 붙여 소유자에게 한 번 묻는다. 그 결정에 기대는 묶음만 멈추고 나머지는 계속한다. - 하위 세션이 묻는 질문에는 답하고, 질문 원문과 "답이 매뉴얼에 있었나"를 적어 둔다. ## 8. 보고 형식 소유자에게는 변경 / 확인 / 남은 문제 세 칸으로 쓴다. 하위 세션 보고 양식과 대조표는 design-docs `conventions/delegation-loop.md` 5·6절이다. 소유자가 이미 아는 외부 일(PR 병합, CI runner 켜기)은 남은 문제와 섞지 않는다. ## 9. 자주 하는 실수 - 게이트 목록을 지난 라운드 목록에서 가져와 merge 게이트를 놓친다. `scripts/verify.sh merge`로 stage 전부를 돌린다. - 판정 표를 짝 백엔드 문서만으로 정한다. 코드까지 따라간다. - 다운스트림 파일을 열지 않고 이름으로 추정해 이행 안내를 쓴다. 확인하지 않은 것은 "미확인"으로 쓴다. - `verify:documentation`을 옆 checkout 없는 임시 worktree에서 그냥 `pnpm`으로 돌려 재설치 대기로 멈춘다. `scripts/verify.sh script verify:documentation`으로 돌린다(설치를 먼저 한다). - 제거 드릴을 `npm run`으로 돌려 모든 검사가 `Unknown command`로 실패한다. `corepack pnpm`만 쓴다. - PR을 만들기 전에 그 head 브랜치의 열린·닫힌 PR과 base 상태를 보지 않아 이미 병합된 커밋으로 PR을 또 만든다. Gitea API(`/api/v1/repos///pulls?state=all`)로 먼저 본다.