Files
clean-architecture-frontend…/docs/work/delegate.md
T
DongHyeonka 3524d6b00b docs(work): 작업 매뉴얼 docs/work/를 두고 개선 매뉴얼 초안을 흡수한다
프론트에는 맡은 일별 작업 절차서가 없었다. 세션은 루트 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
2026-11-08 17:27:39 +09:00

11 KiB

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

총괄 세션이 일을 나누고, brief를 쓰고, 결과를 대조하고, 합치는 절차다. 공용 절차(brief 양식, 보고 양식, 대조, 교훈 정리, 장부, 지표)의 정본은 design-docs conventions/delegation-loop.md다. 이 playbook은 그것을 다시 쓰지 않고, 이 repo의 일을 나누는 법만 더한다.

총괄
  ├─ 리뷰 라운드: 게이트 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 4.1절), 보고 형식.
  • 「이미 아는 것」에는 reference/decisions.md의 결정을 내용으로 옮긴다. 번호만 쓰지 않는다.
  • 결론을 미리 주지 않는다. 총괄이 만든 변경을 리뷰시킬 때는 코드만 주고 결론은 주지 않는다.
  • 수정 묶음 brief에는 공통 지시를 넣는다: RED 먼저, 논리 변경 하나에 커밋 하나, 커밋 규칙, AI 꼬리말 금지, corepack pnpm, 무거운 실행은 desktop 공유 잠금 아래. 보고의 「새로 가정하는 것」 칸을 요구한다.
  • 하위 세션이 결정이 필요한 것을 만나면 총괄에 한 번 묻고 기다린다. 스스로 정하지 않는다.
  • 대조할 때: 보고의 명령·테스트 수를 desktop 로그(/tmp/claude-gates/<로그 이름>/summary.txt)에서 찾는다. High 이상과 새 P1은 총괄이 코드에서 직접 다시 확인한다.
  • 수정 결과의 "고침"을 그대로 믿지 않는다. 다음 리뷰가 ID별로 다시 판정한다.
  • 교훈을 보낼 곳: 그 playbook의 「자주 하는 실수」, 코드 결함 모양은 reference/defect-patterns.md, 거짓 통과는 reference/gates.md 6절, 근거는 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 4.1절만 자기 환경으로 바꾼다.

5. 완료 기준

  • 하위 세션마다 brief가 양식대로이고 자리표시자가 없다.
  • 보고를 diff·커밋·로그와 대조했고 불일치를 셌다.
  • 합친 트리에서 merge 단계가 통과했다(desktop 로그).
  • 리뷰·수정 반복이면 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)로 먼저 본다.