Files
clean-architecture-backend-…/docs/work/delegate.md
T
DongHyeonka c67c713177 feat(agents)!: Agent 금지를 풀고 결과만 돌려주는 서브에이전트 셋을 둔다
Agent 도구를 프로젝트 설정으로 막아 두어서, 넓은 검색·구조 리뷰·앱을
띄워 보는 확인처럼 결과만 받으면 되는 일도 메인 세션 컨텍스트에 쌓이거나
하위 세션을 따로 띄워야 했다. 소유자가 2026-11-07에 금지를 풀고, 결과만
받는 일은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야
하는 위임은 하위 세션으로 나누기로 정했다(design-docs
harness/01-harness-design.md 8절, 13절 Q5).

- .claude/settings.json에서 "Agent" deny를 지웠다(.env deny는 남긴다).
- .claude/agents/: arch-reviewer(HARD-STOP 1~5·registry를 읽기만 하고
  판정), verify-api(desktop에서 공유 잠금 아래 bootstrap-local.sh로 앱을
  띄워 health와 지정 endpoint를 호출), code-simplifier(동작을 바꾸지
  않는 단순화 제안). 셋 다 Edit·Write 도구가 없다.
- 나누는 기준을 AGENTS.md 「일하는 방식」과 docs/work/delegate.md
  4.3절에 썼다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는
  직접 하거나 하위 세션에 맡긴다.
- scripts/tests/test_claude_setup.py: deny가 없고, 정의마다 이름·발동
  조건·도구 목록이 있고, 쓰기 도구가 없고, verify-api가 desktop 절차를
  따르는지 본다.

버린 대안: 금지 유지(설계 권함, 소유자가 자료 쪽으로 정함), Explore만
허용하는 훅(맨 deny를 빼면 allow로 예외를 못 판다).

위험: 서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지
못한다(arch-reviewer, verify-api). 정의 본문이 읽기 명령만 쓰라고 하고,
노트북 Gradle·Docker는 소유자 전역 훅이 서브에이전트 안에서도 막는다.
데스크톱 앱에서 서브에이전트 기록이 소유자에게 어떻게 보이는지는 확인하지
못했다.

검증: python3 -m unittest discover -s scripts/tests rc=0. arch-reviewer에
Edit를 더한 사본, Agent deny를 되살린 사본에서 각각 시험 1건이 실패했다.
check-work-docs·check-docs rc=0.

BREAKING CHANGE: 파생 서비스에서도 Agent 도구가 열린다. 막으려면 서비스
설정에 deny를 남긴다. docs/upgrade/2026-11-harness.md 2절 5행.
2026-11-07 22:08:42 +09:00

12 KiB

총괄 — 큰 일을 나눠 다른 세션에 맡긴다

총괄 세션이 일을 나누고, 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 4.1절 「push 전에 검증하기」). main 병합·main push는 소유자가 한다.
  • 마감과 보고 받을 방법.

3. 크기와 사고 순서

  • 크기는 총괄이 정해 brief에 적는다. 정의는 design-docs conventions/work-thinking-order.md 2절이다.
  • 큰 일은 하위 세션이 1~5단계와 대안 비교까지만 하고 멈추게 brief를 쓴다. 소유자 검토 뒤 만들기를 다시 맡긴다.
  • 총괄 자신의 선행 사례는 지난 라운드의 나누는 법이다: 가장 최근 리뷰 README의 영역 표와 처리 표, evidence.md 2절.
  • 스킬: delegate(소유자 환경의 실행판)가 있으면 쓴다. 정본과 다르면 정본이 맞다.

4. 절차

4.1 맡기고 닫는 순서

design-docs conventions/delegation-loop.md 3절 순서대로 한다: 크기 → 나누기(4.2절) → 기준 커밋 → brief(그 문서 4절 양식, 60줄 이하) → 하위 세션 띄우기 → 보고 대조(그 문서 6절) → 합치기 → 교훈 정리(그 문서 7절) → 장부 한 줄(그 문서 8절) → 소유자 보고.

이 repo에서 더할 것:

  • brief의 「작업 종류」는 이 repo의 docs/work/<종류>.md다. 「이미 아는 것」에는 reference/decisions.md의 결정을 내용으로 옮긴다. 검증 명령은 reference/gates.md와 빌드 파일에서 실제 태스크 이름을 확인해 쓴다.
  • 검증 칸에는 실행 위치와 증거 위치를 쓴다: desktop worktree, flock /tmp/claude-gates/heavy.lock, 로그 ~/<작업 이름>-logs/(operate.md 4.1절). 7절에는 커밋 허용과 자기 브랜치 push 허용을 따로 쓴다.
  • 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸과 「정한 기본값」부터 보라고 적고, 지난 라운드에서 열린 채 넘어온 「Declined to judge」와 README 남은 항목을 다시 판정시킬지도 적는다.
  • 수정 보고를 받으면 「정한 기본값」을 리뷰 README 처리 표와 reference/decisions.md 기본값 행으로, 「범위 밖에서 본 것」을 README 남은 항목으로 옮긴다(reference/review-criteria.md 10절 「확인 리뷰 라운드의 README 절」). 옮기지 않은 기본값은 확인 리뷰가 볼 곳이 없다.
  • 리뷰 brief에는 쓸 심각도 체계(reference/review-criteria.md 3절)와 "발견마다 이번 수정이 만들었나 / 이전부터"를 요구한다.
  • 독립 리뷰어 둘(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/gates.md 6절, 근거는 evidence.md.

4.2 나누는 법 — 이 repo

영역은 가장 최근 리뷰 README의 영역 표를 다시 쓴다. 없으면 아래를 쓴다. 영역 하나에 하위 세션 하나다.

영역 경로
core·application src/domain-core, src/application-*, src/shared-contract
inbound 전송 src/adapter/inbound/*, src/platforms/grpc/*·src/platforms/grpc-advanced/*(optional 빌드)
persistence src/adapter/outbound/persistence-*, 마이그레이션
outbound capability 그 밖의 src/adapter/outbound/*, 멱등성 store
messaging src/platforms/messaging/*, src/adapter/outbound/messaging
bootstrap·build·CI src/app-bootstrap, src/composition/*, src/build-logic, src/build.gradle, .github/
보안(영역을 가로질러) 인증·인가 체인, 비밀, 공개 경로
문서 docs/

두 세션이 동시에 만지면 손으로 풀어야 하는 파일이다. 한 세션만 맡기거나, 총괄이 합칠 때 직접 고친다.

파일 왜
docs/upgrade/ 안내 문서 묶음마다 행을 더해 번호가 겹친다
docs/reviews/<폴더>/README.md 처리 표·결정의 답·게이트 기록·남은 것은 총괄이 쓴다. 리뷰어는 자기 라운드 색인 절 하나만 쓴다(improve.md 4.1절 7단계)
src/config/architecture/modules.json, src/settings.gradle registry 하나가 모든 leaf를 정한다
src/gradle/libs.versions.toml, lockfile 의존성을 바꾸면 lockfile 전체가 바뀐다
src/build.gradle, src/app-bootstrap/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/·agents/, scripts/hooks/ 모든 세션이 읽거나 모든 세션에 걸린다
.github/workflows/* 단계 검사가 workflow 전체를 읽는다

나눌 때 지킬 것:

  • 두 묶음이 같은 파일을 건드리지 않게 나눈다.
  • 묶음마다 그 시점 최신 기준에서 시작한다.
  • 묶음 크기 상한을 지킨다(improve.md 4.4절: 영역 하나, 발견 8건 이하, 확인 리뷰당 추가 1,500줄 이하).
  • 전 leaf의 import를 바꾸는 묶음은 나머지를 합친 뒤 혼자 마지막에 한다.
  • 같은 결함을 두 영역이 보면 한 묶음에만 배정한다.
  • 합칠 때는 하위 브랜치를 모아 reference/gates.md 3절 묶음을 돌린다. 합치기와 그 게이트도 하위 세션에 맡길 수 있다.

4.3 소유자 환경

하위 세션을 띄우는 법, 하위 세션 보고가 총괄에게 전달되는 길이, 공유 노트 폴더, 프론트 repo 일의 경로 같은 소유자 환경 규칙은 design-docs conventions/delegation-loop.md 11절 한 곳에 있다. 다시 쓰지 않는다. 이 repo에서 더할 것은 둘이다.

  • 나누는 기준(소유자 결정 2026-11-07):
    • 파일을 바꾸는 위임, 소유자가 열어 보고 멈출 수 있어야 하는 일은 하위 세션(이 playbook)이다.
    • 결과만 받는 일(넓은 검색, 구조 리뷰 arch-reviewer, 앱을 띄워 보는 확인 verify-api, 단순화 제안 code-simplifier)은 서브에이전트(Agent 도구, 정의는 .claude/agents/)다. 서브에이전트는 파일을 고치지 않는다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다.
    • Gradle·Docker는 누가 돌려도 desktop에서다. 서브에이전트 안에서도 소유자 전역 훅이 노트북 실행을 막는다.
  • 실행 위치(desktop, 공유 잠금, desktop worktree)는 operate.md 4.1절이다.
  • 하위 세션은 공유 노트 폴더의 다른 노트를 먼저 읽는다. 독립 리뷰어 둘은 노트 파일 이름을 서로 다르게 정해 주고, brief에 상대 노트를 읽지 말라고 쓴다.

5. 완료 기준

  • 하위 세션마다 brief가 양식대로이고 자리표시자가 없다.
  • 보고를 diff·커밋·로그와 대조했고 불일치를 셌다.
  • 합친 트리에서 라운드 끝 게이트가 통과했다(desktop 로그).
  • 리뷰·수정 반복이면 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 10절 「ID」).