프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 CLAUDE.md의 리뷰 기준만 읽고 시작했고, 개선 작업 기준은 main에 들어가지 않은 초안 (브랜치 docs/improvement-manual의 docs/improvement 11개)에만 있었다. 백엔드 docs/work/와 같은 모양으로 README(크기·공통 단계·커밋·보고), playbook 여섯(new-feature, improve, research-design, docs-writing, operate, delegate, 모두 같은 9절 뼈대), reference 일곱(gates, review-criteria, structure, testing, performance, defect-patterns, decisions)과 evidence.md를 둔다. 초안의 장을 나눠 옮긴 표는 evidence.md 1.1절이다. SPEC.md의 공통 완료 기준 9개는 improve.md 5절로 옮겨, 문서 체계 정리가 SPEC.md를 이력으로 옮길 수 있게 한다. 진입 문서에는 지난 리뷰 ID를 쓰지 않고 내용과 날짜로 쓴다. ID는 evidence.md와 결정·결함 패턴 색인에만 둔다. 결함 패턴 번호 P-NN은 결정 번호 꼴과 겹쳐 영역 글자+번호(G·T·C·S·W·B)로 다시 매기고 옛 번호 대응을 evidence.md 4절에 남겼다. 열린 결정 대기는 2026-11-06 리뷰 기준으로 갱신했다. 버린 대안: 초안처럼 docs/improvement/ 장 번호 체계를 유지하기. 백엔드와 진입 경로·검사기가 갈라진다. 위험·한계: 이 커밋만으로는 문서 검사 범위 밖이다. docs/README.md가 이 폴더를 링크하는 커밋부터 verify:documentation이 경로를 본다. cold-read 시험은 하지 않았다. 검증: python3 scripts/check-work-docs.py rc=0(뒤 커밋에서 더함). Refs: design-docs harness/01-harness-design.md 13절, PR #6
125 lines
11 KiB
Markdown
125 lines
11 KiB
Markdown
# 총괄 — 큰 일을 나눠 다른 세션에 맡긴다
|
|
|
|
총괄 세션이 일을 나누고, 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/<owner>/<repo>/pulls?state=all`)로 먼저 본다.
|