Files
DongHyeonka c611b06f03
pr / vulnerabilities (pull_request) Canceled after 0s
pr / done (pull_request) Canceled after 0s
pr / gradle (pull_request) Canceled after 8m18s
feat(claude): 분야 전문가를 지식 스킬 열 개와 렌즈 리뷰어로 두고 협업 명단을 붙인다
문제: 하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·API 계약·
빌드·시험·문서·도메인의 이 repo 규칙(적용된 마이그레이션 금지, 잠금 상한,
동시 인덱스 빌드, env 키 레지스트리 등)은 문서에 흩어져 있어, 세션이 그
문서를 찾아 읽어야만 지킨다. 여러 분야에 걸친 일을 누가 보고 어떻게
합치는지도 정한 곳이 없다.

고른 방법(소유자 결정 2026-11-11 「W3 설계대로」):
- 지식 스킬 be-* 10개(.claude/skills/). 각자 paths를 걸어 그 분야 파일을
  만질 때만 목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 →
  검증 → 이 repo에서 정한 것 순서이고, 정본 문서를 가리킨다. 초안은 이
  repo 문서만 본 서브에이전트가 썼고, 경로는 relayout 배치에 맞췄다.
- 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는
  be-domain을 미리 싣고 lead 공통 양식으로 돌려준다.
- .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의
  「함정」·「검증」을 보게 하는 두 줄(평가에서 스킬 호출이 5번 중 2번이었다).
- docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도·충돌·비용. 루트
  AGENTS.md 한 줄, CLAUDE.md 두 줄 고침(10줄 상한 유지), README 3절 4단계와
  delegate.md 4.3절에 가리키는 말.
- 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 지식 스킬의 paths·
  설명 300자·금지어·절 순서·150줄, 모든 paths glob이 추적 파일에 걸림,
  명단이 모든 전문가를 담음.
버린 대안: 분야마다 서브에이전트. Anthropic 2026-10-22·2026-01-23·2026-04-07
글이 반대하고, 설명이 모든 세션에 든다.

위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이
병합돼야 받는다. 그전에는 lead를 가리키는 문장이 설명만 남는다.

검증: python3 -m unittest discover -s scripts/tests → 154건 통과. 새 시험 6개는
조건을 깰 때마다 실패했다. scripts/verify.sh docs → rc=0.
2026-11-11 23:19:44 +09:00

132 lines
13 KiB
Markdown

# 총괄 — 큰 일을 나눠 다른 세션에 맡긴다
총괄 세션이 일을 나누고, brief를 쓰고, 결과를 대조하고, 합치는 절차다. 공용 절차(brief 양식, 보고 양식, 대조, 교훈 정리, 장부, 지표, cold-read 시험)의 정본은 design-docs `conventions/delegation-loop.md`다. 이 playbook은 그것을 다시 쓰지 않고, 이 repo의 일을 나누는 법만 더한다.
## 1. 언제 쓰나
- 일이 커서 여러 세션으로 나눠야 할 때: 전체 리뷰, 영역별 수정 묶음, 리뷰와 수정과 확인 리뷰의 반복, 여러 playbook에 걸친 일.
- 세션 하나가 끝까지 할 수 있는 일이면 이 playbook이 아니다. 그 일의 playbook을 쓴다.
- 맡은 쪽(하위 세션)은 이 playbook이 아니라 brief가 가리킨 playbook을 따른다.
## 2. 받아야 할 것
- 소유자의 목표와 이미 정한 결정. 큰 일이면 소유자가 계획을 검토한 시각.
- 결과가 올라갈 브랜치와 그 최신 커밋(기준 커밋).
- 커밋 허용과 자기 브랜치 push 허용. brief 7절에 따로 적는다. push 없이도 desktop 검증은 된다([operate.md](operate.md) 4.1절 「push 전에 검증하기」). main 병합·main push는 소유자가 한다.
- 마감과 보고 받을 방법.
## 3. 크기와 사고 순서
- 크기는 총괄이 정해 brief에 적는다. 정의는 design-docs `conventions/work-thinking-order.md` 2절이다.
- 큰 일은 하위 세션이 1~5단계와 대안 비교까지만 하고 멈추게 brief를 쓴다. 소유자 검토 뒤 만들기를 다시 맡긴다.
- 총괄 자신의 선행 사례는 지난 라운드의 나누는 법이다: 가장 최근 리뷰 README의 영역 표와 처리 표, [evidence.md](evidence.md) 2절.
- 스킬: `delegate`(소유자 환경의 실행판)가 있으면 쓴다. 정본과 다르면 정본이 맞다.
## 4. 절차
### 4.1 맡기고 닫는 순서
design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 → 나누기(4.2절) → 기준 커밋 → brief(그 문서 4절 양식, 60줄 이하) → 하위 세션 띄우기 → 보고 대조(그 문서 6절) → 합치기 → 교훈 정리(그 문서 7절) → 장부 한 줄(그 문서 8절) → 소유자 보고.
이 repo에서 더할 것:
- 착수 보고(이해한 것, 모호한 점과 고른 가정, 예측)는 하위 세션이 공유 노트에 쓰고 기다리지 않는다. 예측과 실측은 그 세션이 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다. 위임 장부 줄은 그 `task`를 가리킨다.
- brief의 「작업 종류」는 이 repo의 `docs/work/<종류>.md`다. 「이미 아는 것」에는 [reference/decisions.md](reference/decisions.md)의 결정을 **내용으로** 옮긴다. 검증 명령은 [reference/gates.md](reference/gates.md)와 빌드 파일에서 실제 태스크 이름을 확인해 쓴다.
- 검증 칸에는 실행 위치와 증거 위치를 쓴다: desktop worktree, `flock /tmp/claude-gates/heavy.lock`, 로그 `~/<작업 이름>-logs/`([operate.md](operate.md) 4.1절). 7절에는 커밋 허용과 자기 브랜치 push 허용을 따로 쓴다.
- 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸과 「정한 기본값」부터 보라고 적고, 지난 라운드에서 열린 채 넘어온 「Declined to judge」와 README 남은 항목을 다시 판정시킬지도 적는다.
- 수정 보고를 받으면 「정한 기본값」을 리뷰 README 처리 표와 [reference/decisions.md](reference/decisions.md) 기본값 행으로, 「범위 밖에서 본 것」을 README 남은 항목으로 옮긴다([reference/review-criteria.md](reference/review-criteria.md) 10절 「확인 리뷰 라운드의 README 절」). 옮기지 않은 기본값은 확인 리뷰가 볼 곳이 없다.
- 리뷰 brief에는 쓸 심각도 체계([reference/review-criteria.md](reference/review-criteria.md) 3절)와 "발견마다 이번 수정이 만들었나 / 이전부터"를 요구한다.
- 독립 리뷰어 둘([improve.md](improve.md) 4.1절의 세 경우)이면 범위·기준 커밋·심각도 체계가 같은 brief 둘을 쓰고, 두 세션을 함께 띄운다. 다른 칸은 셋이다: 정본 리뷰어인지(ID를 매기고 리뷰 폴더에 커밋한다), 출력 위치(다른 쪽은 보고에 두고 `B-NN-MM`), 5절에 "자기 리뷰를 끝내기 전에 상대 리뷰의 브랜치·문서·보고·노트를 읽지 않는다".
- 두 리뷰가 끝나면 총괄이 합친다. 같은 결함(같은 원인·같은 위치)끼리 짝짓고, 다른 쪽에만 있는 결함은 정본 리뷰어에게 보내 탐침으로 다시 확인한 뒤 다음 번호로 넣게 한다. 그 라운드 색인 절은 총괄이 쓰고 대응표(`B-NN-MM` → 정본 ID)를 둔다.
- 겹침 비율(두 리뷰가 모두 찾은 결함 수 / 합친 결함 수)을 그 라운드 색인 절과 design-docs `delegation-loop/metrics.md`의 M11 칸에 적는다. 2~3라운드 기록이 쌓이면 소유자가 이 방식을 다시 본다.
- 대조할 때: 보고의 태스크 이름·테스트 수를 desktop 로그에서 grep으로 찾는다. High·Important 이상은 총괄이 코드에서 직접 다시 확인한다.
- 리뷰 결과를 받으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`로 색인이 빠짐없는지 본다. 색인 절을 총괄이 쓰기 전에는 리뷰어 보고의 표를 `--extra-index <파일>`로 넘겨 본다. 수정 묶음은 색인에서 배정한다.
- 교훈을 보낼 곳: 그 playbook의 「자주 하는 실수」, 코드 결함 모양은 [reference/defect-patterns.md](reference/defect-patterns.md), 거짓 통과는 [reference/gates.md](reference/gates.md) 6절, 근거는 [evidence.md](evidence.md).
### 4.2 나누는 법 — 이 repo
영역은 가장 최근 리뷰 README의 영역 표를 다시 쓴다. 없으면 아래를 쓴다. 영역 하나에 하위 세션 하나다.
| 영역 | 경로 |
| --- | --- |
| core·application | `src/domain/core`, `src/application/*`, `src/shared-contract` |
| inbound 전송 | `src/adapter/inbound/*`. gRPC 플랫폼 라이브러리는 별도 repo `grpc-library`에서 고친다(`reference/related-repos.md`) |
| persistence | `src/adapter/outbound/persistence-*`, 마이그레이션 |
| outbound capability | 그 밖의 `src/adapter/outbound/*`, 멱등성 store |
| messaging | `src/adapter/inbound/messaging`, `src/adapter/outbound/messaging*`. 메시징 라이브러리는 별도 repo `messaging-library`에서 고친다(`reference/related-repos.md`) |
| bootstrap·build·CI | `src/bootstrap/*`(조립 루트 `app` 포함), `build-logic`, `build.gradle`, `gradle/`, `.gitea/`, `.github/` |
| 보안(영역을 가로질러) | 인증·인가 체인, 비밀, 공개 경로 |
| 문서 | `docs/` |
두 세션이 동시에 만지면 손으로 풀어야 하는 파일이다. 한 세션만 맡기거나, 총괄이 합칠 때 직접 고친다.
| 파일 | 왜 |
| --- | --- |
| `docs/upgrade/` 안내 문서 | 묶음마다 행을 더해 번호가 겹치고, 머리 「커밋:」 줄을 여럿이 고치면 충돌한다. 묶음은 「커밋:」 줄을 고치지 않고 보고에 커밋을 적는다. 총괄이 합칠 때 한 번에 적는다 |
| `docs/reviews/<폴더>/README.md` | 처리 표·결정의 답·게이트 기록·남은 것은 총괄이 쓴다. 리뷰어는 자기 라운드 색인 절 하나만 쓴다([improve.md](improve.md) 4.1절 7단계) |
| `gradle/modules.json`, `settings.gradle` | registry 하나가 모든 leaf를 정한다 |
| `gradle/libs.versions.toml`, lockfile | 의존성을 바꾸면 lockfile 전체가 바뀐다 |
| `build.gradle`, `src/bootstrap/app/build.gradle` | 라이프사이클과 기본 조립 |
| `docs/registries/*.yaml` | 오류 코드·env 키·지표를 여러 기능이 함께 쓴다 |
| `docs/architecture/*-api-surface.txt`, `docs/security/public-paths-snapshot.txt` | 생성되는 스냅숏이다 |
| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`·`skills/`·`agents/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 |
| `.gitea/workflows/*`, `strictLaneStages`(`build.gradle`) | 단계 job의 모양을 함께 검사한다 |
나눌 때 지킬 것:
- 두 묶음이 같은 파일을 건드리지 않게 나눈다.
- 묶음마다 그 시점 최신 기준에서 시작한다.
- 묶음 크기 상한을 지킨다([improve.md](improve.md) 4.4절: 영역 하나, 발견 8건 이하, 확인 리뷰당 추가 1,500줄 이하).
- 전 leaf의 import를 바꾸는 묶음은 나머지를 합친 뒤 혼자 마지막에 한다.
- 같은 결함을 두 영역이 보면 한 묶음에만 배정한다.
- 같은 파일·장치에서 결함이 두 라운드 연속 나오면 다음 묶음은 수정이 아니라 「이 장치가 필요한가, 형식을 좁혀 없앨 수 있나」를 보는 조사([research-design.md](research-design.md))로 맡긴다.
- 합칠 때 충돌 해결 밖에서 새로 고칠 것이 생기면 병합 커밋에 넣지 않고 병합 뒤 따로 커밋한다. 병합 커밋에는 충돌 해결만 둔다.
- 합칠 때는 하위 브랜치를 모아 [reference/gates.md](reference/gates.md) 3절 묶음을 돌린다. 합치기와 그 게이트도 하위 세션에 맡길 수 있다.
### 4.3 소유자 환경
하위 세션을 띄우는 법, 하위 세션 보고가 총괄에게 전달되는 길이, 공유 노트 폴더, 프론트 repo 일의 경로 같은 소유자 환경 규칙은 design-docs `conventions/delegation-loop.md` 11절 한 곳에 있다. 다시 쓰지 않는다. 이 repo에서 더할 것은 둘이다.
- 나누는 기준(소유자 결정 2026-11-07):
- 파일을 바꾸는 위임, 소유자가 열어 보고 멈출 수 있어야 하는 일은 하위 세션(이 playbook)이다.
- 결과만 받는 일(넓은 검색, 렌즈를 받는 분야 리뷰 `reviewer`, 구조 리뷰 `arch-reviewer`, 앱을 띄워 보는 확인 `verify-api`, 단순화 제안 `code-simplifier`)은 서브에이전트(Agent 도구, 정의는 `.claude/agents/`)다. 렌즈·리뷰어 수·넘김은 [experts.md](experts.md)와 플러그인 `lead` 스킬이다. 서브에이전트는 파일을 고치지 않는다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다.
- Gradle·Docker는 누가 돌려도 desktop에서다. 서브에이전트 안에서도 소유자 전역 훅이 노트북 실행을 막는다.
- 실행 위치(desktop, 공유 잠금, desktop worktree)는 [operate.md](operate.md) 4.1절이다.
- 하위 세션은 공유 노트 폴더의 다른 노트를 먼저 읽는다. 독립 리뷰어 둘은 노트 파일 이름을 서로 다르게 정해 주고, brief에 상대 노트를 읽지 말라고 쓴다.
## 5. 완료 기준
- 하위 세션마다 brief가 양식대로이고 자리표시자가 없다.
- 보고를 diff·커밋·로그와 대조했고 불일치를 셌다.
- 합친 트리에서 라운드 끝 게이트가 통과했다(desktop 로그).
- 리뷰·수정 반복이면 [improve.md](improve.md) 4.5절 멈춤 기준이 모두 참이다.
- 교훈 정리와 장부 한 줄을 끝냈다.
- 소유자 보고에 변경 / 확인(명령·결과·커밋) / 남은 문제가 있다.
## 6. 하지 말 것
- 하위 세션의 일을 대신 하지 않는다. 대조에 필요한 읽기와 확인만 직접 한다.
- 보고를 그대로 믿지 않는다. 보고는 E0 증거다.
- 같은 파일을 두 세션에 맡기지 않는다.
- 하위 세션에 main 병합·main push, force push, 다른 브랜치 push를 허용하지 않는다.
- brief에 결정 번호만 쓰지 않는다. 내용을 쓴다.
## 7. 막혔을 때
- 소유자만 정할 수 있는 것은 근거와 권하는 안을 붙여 소유자에게 한 번 묻는다. 그 결정에 기대는 묶음만 멈추고 나머지는 계속한다.
- 하위 세션이 묻는 질문에는 답하고, 질문 원문과 "답이 매뉴얼에 있었나"를 적어 둔다. 장부의 질문 수가 된다.
## 8. 보고 형식
소유자에게는 변경 / 확인 / 남은 문제 세 칸으로 쓴다. 하위 세션 보고 양식과 대조표는 design-docs `conventions/delegation-loop.md` 5·6절이다. 소유자가 이미 아는 외부 일(PR 병합, CI runner 켜기)은 남은 문제와 섞지 않는다.
## 9. 자주 하는 실수
- 영역 문서의 ID를 색인에 손으로 옮기다 빠뜨린다. 색인 검사 스크립트를 돌린다.
- 묶음을 너무 크게 만들어 마감 안에 검증 보고가 오지 않는다. 묶음 크기 상한을 지킨다.
- 하위 세션이 적은 태스크 이름을 확인하지 않고 소유자에게 옮긴다.
- 같은 범위를 두 리뷰에 따로 맡기고(비교 시험 등) ID를 매길 쪽을 정하지 않아, 같은 ID가 다른 결함을 가리킨다. brief에 ID를 매길 리뷰 하나를 정한다(규칙은 [reference/review-criteria.md](reference/review-criteria.md) 10절 「ID」).
- brief에 「다른 PR과 충돌 없음」을 대상 파일 몇 개만 비교해 적는다. 쓰려면 바뀌는 모든 파일을 `git merge-tree --write-tree <base> <브랜치 A> <브랜치 B>`로 본다.
- PR을 만들기 전에 그 head 브랜치의 열린·닫힌 PR과 base 상태를 보지 않아, 이미 병합된 커밋으로 PR을 또 만든다. Gitea API(`/api/v1/repos/<owner>/<repo>/pulls?state=all`)로 먼저 본다.