혼자가 아니라, 팀으로.
일이 한 명에게 버거워질 때 — 나누고, 맡기고, 보고받는 법
에이전트의 조직도
에이전트 한 명에게 모든 걸 맡기면 상자가 차면서 흐려집니다. 사람 조직처럼 나누고 맡기고 보고받으세요.
서브에이전트를 써서 ○○ 폴더 전체를 조사해줘. 목표: ○○이 어디서 처리되는지 찾기. 보고 형식: 관련 파일 경로 + 각 1줄 설명, 최대 15줄. 코드는 수정하지 마.
한 명의 한계
부모의 상자는 계획과 결론만으로 가볍게 유지됩니다 — 회사의 분업·위임·보고와 같은 구조입니다.
자식이 읽은 1만 줄은 자식과 함께 사라지고, 부모에게는 결론 30줄만 남습니다.
지역 변수 = 자식의 탐색·시행착오 반환값 = 요약 보고 호출자 = 부모
이것을 컨텍스트 격리라고 부릅니다 — 서브에이전트를 쓰는 가장 큰 이유.
# ❌ 이렇게 위임하면 "주간보고 폴더 좀 봐줘" # 자식은 부모의 대화를 모릅니다 — # 무엇을? 왜? 어디까지? # 게다가 중간에 되물을 수도 없습니다
# ✅ 업무 지시서 "reports/의 주간보고 150개를 조사해줘. 목표: 장비 EQ-07에서 반복된 알람 유형 찾기 완료 기준: 알람마다 원문 한 줄 근거 반환 형식: 표 — 날짜 | 알람 유형 | 파일명, 최대 20행"
"서브에이전트로 나눠서 조사해줘" "독립적인 부분은 병렬로 진행해줘" "리뷰는 별도 에이전트에게 맡겨줘"
이 한마디면 에이전트가 알아서 자식을 띄웁니다.
.claude/agents/reviewer.md --- name: reviewer description: 코드 리뷰 전문. PR·diff 검토 시 사용 tools: Read, Grep --- 너는 깐깐한 시니어 리뷰어다. …
이름·전문 분야·쓸 수 있는 도구를 적어 두면 필요할 때 같은 역할이 다시 불려 옵니다. 리뷰어에게는 읽기 권한만.
탐색 → 계획 → 구현 → 리뷰. 단계마다 다른 에이전트, 각자 깨끗한 눈.
읽을 건 많고 단계가 뚜렷할 때
독립 작업 여러 개를 동시에. 기다리는 시간이 줄어듭니다.
보고서 10개 요약 · 후보 3개 비교 조사
항목별로 단계를 흘려보내기 — 앞 단계 전체를 기다리지 않고.
문서 50건 추출 → 번역 → 검수
같은 문제를 N번 독립 시도 → 채점·종합. 서로 반박도 시킵니다.
설계안·문안처럼 정답이 여럿일 때
탐색이 읽은 파일 수십 개는 탐색 상자에 두고 갑니다 — 계획은 정리된 보고서만 보고 세웁니다.
리뷰어는 구현자의 사정을 모릅니다. 내가 만든 것은 내 눈에 늘 옳아 보이니까요 — 사람도, 에이전트도.
❌ 혼자 순차 — 파일 5개 × 10분🕐 50분
✅ fan-out — 동시에 5명🕐 10분 + 취합
예: 보고서 10개 요약 · 후보 3개 비교 조사 · 파일별 변환. 걸리는 시간은 줄지만 드는 토큰은 줄지 않습니다.
과제: 문서 여러 건을 추출 → 번역 → 검수로 처리하기 (단계마다 담당 에이전트 1명)
❌ 배리어 — 단계 전체가 끝나야 다음9틱
✅ 파이프라인 — 끝난 것부터 바로 다음5틱 ✂
🙈 시도들은 서로의 답을 못 봅니다 — 독립성이 다양성을 만듭니다.
🥊 한 걸음 더: 🅰에게 🅱를 반박시켜 보세요 — 스스로 매기는 점수보다 냉정합니다.
설계·문안·전략처럼 정답이 여럿일 때만. 비용은 시도 횟수만큼 늡니다.
[x] 1. API 명세 조사 — 완료 (보고서: notes/api.md) [>] 2. 파서 구현 — 에이전트 B 진행 중 [ ] 3. 테스트 작성 — 2번 완료 후 [ ] 4. 문서 갱신
누가 어디까지 했는지가 대화를 새로 시작해도 남습니다.
PLAN.md에 설계와 결정을, NOTES.md에 중간 발견을 — 자식들이 같은 파일을 읽으며 합을 맞춥니다.
자식 A의 발견을 자식 B에게 전하는 가장 싼 방법은 부모의 말이 아니라 파일입니다.
$ git worktree add ../feat-login feature/login
$ git worktree add ../feat-search feature/search
# 같은 저장소, 서로 다른 작업 폴더
에이전트마다 자기 사본 — 같은 파일을 동시에 고쳐도 충돌이 없습니다. 끝나면 브랜치 병합으로 합칩니다.
파이프라인 사이사이에 검사 단계를 심습니다 — 테스트 러너 · 린터 · 리뷰 에이전트. 통과 기준은 작업 목록에 명시.
검사 방법은 검증 세미나의 사다리 그대로입니다.
$ claude -p "어젯밤 실패한 테스트를 분석해서 원인 요약을 report.md로 저장해줘" # 대화창 없이 한 번 실행하고 종료 — 결과는 파일과 표준 출력으로
반복문·크론 작업에 끼워 넣으면 에이전트가 파이프라인의 한 단계가 됩니다. 매일 밤 로그 분석, 매주 문서 갱신.
오케스트레이터 스크립트가 headless 에이전트 여럿을 지휘 — 사람은 시작과 결과 확인만.
PR이 열리면 리뷰 에이전트가 코멘트를 달아둡니다. 사람 리뷰어는 굵은 판단만.
새 이슈에 라벨·우선순위·담당 제안을 자동으로 — 아침 분류 회의가 짧아집니다.
스케줄 트리거로 매일 밤 — 의존성 점검 · 문서 갱신 · 릴리스 노트 초안.
GitHub Actions 같은 CI에 에이전트를 심으면, 트리거(PR·이슈·스케줄)가 상사 역할을 대신합니다.
| 방식 | 계획을 쥔 쪽 | 규모 | 이렇게 시작 |
|---|---|---|---|
| 🧬 서브에이전트 | Claude가 턴마다 | 한 번에 몇 개 | "서브에이전트로 나눠서" · 진행 상황은 /tasks |
| 🗂 에이전트 뷰 | 내가 — 독립 작업을 던져 두고 확인 | 세션 여러 개 | claude agents — 백그라운드 세션을 한 화면에서 |
| 📜 Workflow | 스크립트가 — Claude가 써 주고 다시 돌릴 수 있음 | 수십~수백 개 | "workflow로 해줘" · /workflows로 관전 |
| ☁️ 클라우드 예약 작업 | 스케줄이 — 내 PC가 꺼져도 | 정해진 시각마다 | /schedule "매일 아침 9시에 …" |
💬 말로 시키면
"workflow로 src/ 아래 측정 스크립트 전부를
단위 오류가 있는지 점검하고, 찾은 건
서로 교차 검증한 뒤 보고해줘"
📜 Claude가 쓴 스크립트 (요지)
const files = await agent('점검할 파일 목록') const found = await pipeline(files.list, f => agent(`${f} 단위 오류 점검`)) // 🍴 fan-out const ok = await parallel(found.map(x => () => agent(`반박해 봐: ${x}`))) // ⚖️ 심판
중간 결과는 스크립트 안에 — 메인 대화엔 최종 보고만 돌아옵니다.
잘 된 실행은 /workflows에서 s로 저장 → 다음부턴 /내-이름 한 줄. 중간에 멈춰도 끝난 에이전트는 다시 안 돕니다.
에이전트 25개·150만 토큰을 넘으면 경고가 뜹니다. 폴더 하나로 먼저 시험해 보고 넓히세요.
헷갈리면 혼자가 기본값입니다 — 팀은 병목이 눈에 보일 때만 부르세요.
| 패턴 | 이럴 때 | 이렇게 말하세요 |
|---|---|---|
| 🎭 역할 분담 | 읽을 건 많고 결론은 짧을 때 | "먼저 서브에이전트로 조사해 보고서만 받아줘. 그걸로 계획을 세운 뒤 진행해줘." |
| 🍴 병렬 fan-out | 서로 독립인 일 여러 개 | "이 보고서 10개를 서브에이전트들로 나눠 동시에 요약해줘. 같은 파일은 둘이 건드리지 않게." |
| 🏭 파이프라인 | 항목이 많고 단계가 고정 | "문서마다 추출 → 번역 → 검수 순서로, 끝난 것부터 다음 단계로 넘겨줘." |
| ⚖️ 심판 패널 | 정답이 여럿, 품질이 승부 | "서로 다른 접근으로 3번 따로 시도한 뒤, 비교·채점해서 가장 나은 안을 제안해줘." |
| 🧑💻 그 외 대부분 | 작고 순서가 얽힌 일 | 그냥 혼자 시키고, 결과를 검사합니다 — 그게 가장 빠릅니다. |
지시서에는 항상 — 🎯 목표 · ✅ 완료 기준 · 📦 반환 형식
질문은 지금, 또는 Q&A 위젯으로 받겠습니다.