문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와 리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이 "이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는 없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지), 커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음). 고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs delegation-loop/02-design.md 4~6·10절): - CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본 AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는 곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던 내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은 reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절. - docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개 (new-feature, improve, research-design, docs-writing, operate, delegate, 모두 같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns, decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고 review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에 나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고, improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다. - improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과 수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난 수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25, +13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다. - 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를 README 4절과 AGENTS.md에 같은 말로 적었다. - 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인 (reference/decisions.md, reference/defect-patterns.md)에만 둔다. - 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md, docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운 CLAUDE.md 「Layer workflow」를 가리키던 줄). 위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라 초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어 docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/ 본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의 성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다. 검증 - python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80, playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄 - python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0 - CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest .guidanceNamesTheArchitectureSourceSetTask가 기대하는 "./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는 이 커밋을 push한 뒤 desktop에서 돌린다
117 lines
8.7 KiB
Markdown
117 lines
8.7 KiB
Markdown
# 총괄 — 큰 일을 나눠 다른 세션에 맡긴다
|
|
|
|
총괄 세션이 일을 나누고, brief를 쓰고, 결과를 대조하고, 합치는 절차다. 공용 절차(brief 양식, 보고 양식, 대조, 교훈 정리, 장부, 지표, cold-read 시험)의 정본은 design-docs `conventions/delegation-loop.md`다. 이 playbook은 그것을 다시 쓰지 않고, 이 repo의 일을 나누는 법만 더한다.
|
|
|
|
## 1. 언제 쓰나
|
|
|
|
- 일이 커서 여러 세션으로 나눠야 할 때: 전체 리뷰, 영역별 수정 묶음, 리뷰와 수정과 확인 리뷰의 반복, 여러 playbook에 걸친 일.
|
|
- 세션 하나가 끝까지 할 수 있는 일이면 이 playbook이 아니다. 그 일의 playbook을 쓴다.
|
|
- 맡은 쪽(하위 세션)은 이 playbook이 아니라 brief가 가리킨 playbook을 따른다.
|
|
|
|
## 2. 받아야 할 것
|
|
|
|
- 소유자의 목표와 이미 정한 결정. 큰 일이면 소유자가 계획을 검토한 시각.
|
|
- 결과가 올라갈 브랜치와 그 최신 커밋(기준 커밋).
|
|
- 커밋·push 허용 범위. 하위 세션 브랜치 push는 desktop 검증에 필요하다. 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에서 더할 것:
|
|
|
|
- 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절). desktop 검증이 필요하면 7절에 자기 브랜치 push를 허용한다.
|
|
- 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸부터 보라고 적는다.
|
|
- 리뷰 brief에는 쓸 심각도 체계([reference/review-criteria.md](reference/review-criteria.md) 3절)와 "발견마다 이번 수정이 만들었나 / 이전부터"를 요구한다.
|
|
- 대조할 때: 보고의 태스크 이름·테스트 수를 desktop 로그에서 grep으로 찾는다. High·Important 이상은 총괄이 코드에서 직접 다시 확인한다.
|
|
- 리뷰 결과를 받으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`로 색인이 빠짐없는지 본다. 수정 묶음은 색인에서 배정한다.
|
|
- 교훈을 보낼 곳: 그 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/*`, `src/grpc/*`·`src/grpc-advanced/*`(optional 빌드) |
|
|
| persistence | `src/adapter/outbound/persistence-*`, 마이그레이션 |
|
|
| outbound capability | 그 밖의 `src/adapter/outbound/*`, 멱등성 store |
|
|
| messaging | `src/messaging/*`, `src/adapter/outbound/messaging` |
|
|
| bootstrap·build·CI | `src/app-bootstrap`, `src/composition/*`, `src/build-logic`, `src/build.gradle`, `.github/` |
|
|
| 보안(영역을 가로질러) | 인증·인가 체인, 비밀, 공개 경로 |
|
|
| 샘플·문서 | `src/sample-portfolio`, `docs/` |
|
|
|
|
두 세션이 동시에 만지면 손으로 풀어야 하는 파일이다. 한 세션만 맡기거나, 총괄이 합칠 때 직접 고친다.
|
|
|
|
| 파일 | 왜 |
|
|
| --- | --- |
|
|
| `docs/upgrade/` 안내 문서 | 묶음마다 행을 더해 번호가 겹친다 |
|
|
| `docs/reviews/<폴더>/README.md` | 처리 표·결정·게이트 기록은 총괄이 쓴다 |
|
|
| `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/` | 모든 세션이 읽는다 |
|
|
| `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 |
|
|
|
|
나눌 때 지킬 것:
|
|
|
|
- 두 묶음이 같은 파일을 건드리지 않게 나눈다.
|
|
- 묶음마다 그 시점 최신 기준에서 시작한다.
|
|
- 묶음 크기 상한을 지킨다([improve.md](improve.md) 4.4절: 영역 하나, 발견 8건 이하, 확인 리뷰당 추가 1,500줄 이하).
|
|
- 전 leaf의 import를 바꾸는 묶음은 나머지를 합친 뒤 혼자 마지막에 한다.
|
|
- 같은 결함을 두 영역이 보면 한 묶음에만 배정한다.
|
|
- 합칠 때는 하위 브랜치를 모아 [reference/gates.md](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](operate.md) 4.1절이다.
|
|
|
|
## 5. 완료 기준
|
|
|
|
- 하위 세션마다 brief가 양식대로이고 자리표시자가 없다.
|
|
- 보고를 diff·커밋·로그와 대조했고 불일치를 셌다.
|
|
- 합친 트리에서 라운드 끝 게이트가 통과했다(desktop 로그).
|
|
- 리뷰·수정 반복이면 [improve.md](improve.md) 4.5절 멈춤 기준이 모두 참이다.
|
|
- 교훈 정리와 장부 한 줄을 끝냈다.
|
|
- 소유자 보고에 변경 / 확인(명령·결과·커밋) / 남은 문제가 있다.
|
|
|
|
## 6. 하지 말 것
|
|
|
|
- 하위 세션의 일을 대신 하지 않는다. 대조에 필요한 읽기와 확인만 직접 한다.
|
|
- 보고를 그대로 믿지 않는다. 보고는 E0 증거다.
|
|
- 같은 파일을 두 세션에 맡기지 않는다.
|
|
- 하위 세션에 main 병합·push, force push, 다른 브랜치 push를 허용하지 않는다.
|
|
- brief에 결정 번호만 쓰지 않는다. 내용을 쓴다.
|
|
|
|
## 7. 막혔을 때
|
|
|
|
- 소유자만 정할 수 있는 것은 근거와 권하는 안을 붙여 소유자에게 한 번 묻는다. 그 결정에 기대는 묶음만 멈추고 나머지는 계속한다.
|
|
- 하위 세션이 묻는 질문에는 답하고, 질문 원문과 "답이 매뉴얼에 있었나"를 적어 둔다. 장부의 질문 수가 된다.
|
|
|
|
## 8. 보고 형식
|
|
|
|
소유자에게는 변경 / 확인 / 남은 문제 세 칸으로 쓴다. 하위 세션 보고 양식과 대조표는 design-docs `conventions/delegation-loop.md` 5·6절이다. 소유자가 이미 아는 외부 일(PR 병합, CI runner 켜기)은 남은 문제와 섞지 않는다.
|
|
|
|
## 9. 자주 하는 실수
|
|
|
|
- 영역 문서의 ID를 색인에 손으로 옮기다 빠뜨린다. 색인 검사 스크립트를 돌린다.
|
|
- 묶음을 너무 크게 만들어 마감 안에 검증 보고가 오지 않는다. 묶음 크기 상한을 지킨다.
|
|
- 하위 세션이 적은 태스크 이름을 확인하지 않고 소유자에게 옮긴다.
|