Files
clean-architecture-backend-…/docs/work/delegate.md
T
DongHyeonka 38891071d6 feat(hooks)!: 편집 직후 포맷·레이어·문서 알림과 migration 차단 훅을 건다
지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사
실패는 desktop 게이트에서야 보이고, 이미 적용된 migration을 고쳐도
desktop의 AppliedMigrationImmutabilityTest가 돌 때까지 아무도 모른다.
소유자가 2026-11-07에 편집 훅이 그 파일 하나만 Gradle 없이 포맷·린트하고,
전체 검사는 턴 끝 넛지로, 되돌릴 수 없는 것만 막기로 정했다
(design-docs harness/01-harness-design.md 5절, 13절 Q6·Q7).

scripts/hooks/hooks.py 하나에 이벤트 넷(표준 라이브러리만):
- pre-edit H13: 편집 대상이 applied-migrations.sha256에 있는 migration이면
  종료 코드 2로 막고 새 버전 파일을 더하라고 안내한다.
- post-edit 포맷: src/**/*.java 한 파일을 google-java-format으로 맞춘다.
  버전은 카탈로그 googleJavaFormat, jar는 Gradle 캐시에 이미 있는 것만
  쓰고(받거나 설치하지 않음), 옵션은 Spotless 단계와 같게
  --skip-reflowing-long-strings --replace. 이 옵션으로 Spotless 대상
  파일 전부를 dry-run 하면 차이가 0이었다(차이는 Spotless를 쓰지 않는
  build-logic뿐이라 훅도 제외한다). 파일이 바뀌면 다시 읽으라고 알린다.
- post-edit N1: registry로 leaf를 찾고 import를 순수성 목록
  (DomainPurityArchitectureTest, verifyApplicationCoreDependencyPurity와
  같은 패키지)과 allowed_dependencies 전이 closure에 대 본다.
- post-edit N2: 문서 편집 뒤 check-work-docs·check-docs의 실패 줄.
- post-bash·stop N5: Java를 고친 뒤 ssh desktop gradlew 실행이 없으면
  턴 끝을 한 번 막고 desktop 검증이나 못 돌린 이유를 쓰라고 한다.
- 권한: 실제 .env·.env.local·.env.lane 읽기·쓰기 deny(예시 파일은 둠).

버린 대안: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로
정함), 편집마다 desktop 원격 실행(왕복 비용), checkstyle 한 파일
(Gradle 없이 classpath를 맞출 수 없다. 린트는 N1이 맡는다).

위험: 이 세션에서 settings.json을 바꿔도 훅은 돌지 않았다. 훅은 세션이
시작할 때 읽힌다. 그래서 settings.json이 부르는 명령에 같은 입력을 넣어
확인했다. N1은 게이트의 일부만 본다. 정본은 architectureCheck다.

검증: python3 -m unittest discover -s scripts/tests rc=0(훅 시험 29,
그중 실제 포매터 시험은 이 노트북 캐시의 1.35.0 jar로 돌았다). 변이
시험: 조건 10개를 하나씩 끈 사본마다 시험이 1~2건 실패했다. 실제
운영 소스 3,230개에 N1을 돌려 걸림 0. 편집 한 번 훅 시간 Java 0.3초,
문서 1.2초. check-docs·check-work-docs·check-repo-layout rc=0.

BREAKING CHANGE: 파생 서비스에도 같은 훅과 .env deny가 걸린다.
docs/upgrade/2026-11-harness.md 2절 4행.
2026-11-07 22:06:50 +09:00

11 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/, 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에서 더할 것은 둘이다.

  • Agent 도구(세션 안의 하위 에이전트)는 이 repo의 .claude/settings.json이 막는다. 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 그 세션이 직접 하거나, 이 playbook대로 별도 세션에 맡긴다. 막혔다고 Agent로 우회하지 않는다.
  • 실행 위치(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」).