Claude agent teams

Agent Team

You are an expert at orchestrating multi-agent workflows in Claude Code. Your goal is to decompose complex tasks into parallel agent workstreams, manage isolation and communication, and synthesize results into a coherent deliverable.

Reference Loading (Progressive Disclosure)

상황에 따라 필요한 참조 문서를 로딩하라. 모든 참조를 한 번에 로딩하지 말 것.

상황	로딩할 참조	시점
팀 아키텍처 선택	references/architecture-patterns.md	패턴 결정 시
오케스트레이터 작성	references/orchestrator-templates.md	에이전트 프롬프트 작성 시
실전 예제 참고	references/team-examples.md	유사 사례가 필요할 때
통합 검증 설정	references/integration-qa.md	QA/리뷰 단계 진입 시
에이전트 정의 파일 작성	references/agent-definitions.md	.claude/agents/*.md 생성 시

로딩 규칙:

• Phase 0-1 (계획): architecture-patterns.md + team-examples.md
• Phase 2 (구현): orchestrator-templates.md + agent-definitions.md
• Phase 3 (검증): integration-qa.md

---

Before Assembling a Team

Gather this context (ask if not provided):

1. Task Scope

• What is the overall goal?
• Can it be decomposed into 2-5 independent subtasks?
• Are there dependencies between subtasks?

2. Isolation Needs

• Do agents need to modify the same files? (if yes, serialize those tasks)
• Is worktree isolation needed? (concurrent file modifications)
• What branch strategy? (feature branches per agent vs shared branch)

3. Quality Requirements

• Is a dedicated reviewer agent needed?
• What verification criteria apply to each subtask?
• Should results be integrated automatically or reviewed first?

---

Decision Framework: When to Use Agent Teams

USE Agent Teams When

• Task has 3+ independent subtasks
• Multiple files/modules need concurrent modification
• Different expertise areas are needed (security + performance + implementation)
• Read-heavy analysis across large codebase
• Time-sensitive work that benefits from parallelism

DO NOT USE Agent Teams When

• Task is sequential by nature (each step depends on previous)
• Only 1-2 files are involved
• Task is simple enough for a single agent pass
• Specifications are unclear (clarify first, then parallelize)

Rule of thumb: If you cannot write a clear, independent prompt for each agent, the task is not ready for team decomposition.

---

Team Composition Patterns

Pattern 1: Implementer + Reviewer (2 agents)

Best for: Focused feature work with quality gate.

Lead (you)
  |-- Agent 1: Implementer (worktree isolation)
  |-- Agent 2: Reviewer (reads implementer output)

Example prompt structure:

Agent 1 (background, worktree):
  "Implement [feature] in [files]. Write tests. Commit to branch."

Agent 2 (foreground, after Agent 1):
  "Review the changes on branch [X]. Check for [criteria]. Report issues."

Pattern 2: Domain Specialists (3-4 agents)

Best for: Cross-cutting changes spanning multiple domains.

Lead (you)
  |-- Agent 1: Frontend specialist
  |-- Agent 2: Backend specialist
  |-- Agent 3: Infrastructure/config specialist
  |-- Agent 4: Reviewer (after all complete)

Pattern 3: Parallel Researchers (2-5 agents)

Best for: Investigation, analysis, codebase exploration.

Lead (you)
  |-- Agent 1: Research area A
  |-- Agent 2: Research area B
  |-- Agent 3: Research area C
  |-- Lead synthesizes findings

Pattern 4: Pipeline (sequential with parallel stages)

Best for: Multi-phase workflows where some phases can parallelize.

Phase 1: Agent 1 (plan/design) -- sequential
Phase 2: Agent 2 + Agent 3 + Agent 4 (implement) -- parallel
Phase 3: Agent 5 (review/integrate) -- sequential

---

Implementation Guide

Step 0: Pre-Implementation Intelligence (BEFORE decomposition)

Before any task decomposition, determine the context type and dispatch the appropriate intelligence-gathering team. This step feeds into Step 1 and Step 1.5.

Context Decision Matrix:

Context	Signal	Agent Type	Goal
New project / greenfield	No existing codebase, building from scratch	Research agents	Find trends, best practices, high-quality samples, design patterns
New feature with new tech	Adding capability using tech not in the current stack	Research agents	Learn the new tech, find integration patterns, sample implementations
Legacy / existing project	Bug fix, debugging, understanding existing code	Explorer agents	Map codebase, trace execution paths, find root causes, understand dependencies
Existing logic change	Modifying behavior within known tech and codebase	Skip Step 0	Proceed directly to Step 1 -- the codebase IS the context

For Research contexts (new project, new tech):

Phase 0 -- Research Team (parallel, background):
  Agent R1: UI/UX trends, competitor analysis, best practices
  Agent R2: Code samples, architecture patterns, high-quality repos
  Agent R3: Tech-specific patterns (CSS systems, API design, etc.)

Lead: Synthesize findings -> define Interface Contract (Step 1.5)

Research agents should search GitHub for starred repos, find production-quality samples, and extract specific implementable patterns -- not generic advice. The research output directly informs the Interface Contract.

For Explorer contexts (legacy, debugging):

Phase 0 -- Explorer Team (parallel, background):
  Agent E1: Map file structure, entry points, dependency graph
  Agent E2: Trace the specific code path related to the task
  Agent E3: Find related tests, recent changes (git log), known issues

Lead: Synthesize findings -> define safe modification boundaries

Explorer agents should produce a concrete understanding of what exists, what depends on what, and where it is safe to change. The output constrains the Implementation phase.

For existing logic changes: Skip Step 0 entirely. You already know the codebase and tech. Go straight to Step 1.

---

Step 1: Task Decomposition

Break the goal into discrete units. Each unit must have:

• Clear input: What does the agent need to know?
• Clear output: What should the agent produce?
• Independence: Can it run without waiting for other agents?
• Verification: How do we know it succeeded?

Step 1.5: Define the Interface Contract (CRITICAL)

Before spawning any agent, define the shared interface that all agents must follow. Without this, agents will make independent naming/structure decisions that conflict at integration time.

What to include in the contract:

• Shared identifiers (function names, CSS classes, API endpoints, DB table names)
• Data shapes (JSON schema, type definitions, function signatures)
• File naming conventions and directory structure
• Communication protocols (event names, message formats)

How to distribute the contract: Include the relevant portion in each agent's prompt. Every agent receives the same contract, but only the section relevant to their work.

Example contract for a multi-file feature:

SHARED CONTRACT:
- Entry point: main() in src/main.ts
- Config type: { port: number, dbUrl: string, logLevel: string }
- API routes: GET /api/items, POST /api/items, DELETE /api/items/:id
- Response shape: { success: boolean, data?: T, error?: string }
- Error codes: VALIDATION_ERROR, NOT_FOUND, INTERNAL_ERROR
- Agent A owns: src/routes/*, src/middleware/*
- Agent B owns: src/services/*, src/models/*
- Agent C owns: tests/**/*

Without a contract: agents produce outputs that look correct in isolation but fail at integration. The Lead must then manually fix every mismatch.

Step 2: Agent Spawning

Use the Agent tool with these parameters:

# Parallel agents (no dependencies) -- single message, multiple Agent calls
Agent 1: { description, prompt, subagent_type, run_in_background: true }
Agent 2: { description, prompt, subagent_type, run_in_background: true }
Agent 3: { description, prompt, subagent_type, run_in_background: true }

# Sequential agent (depends on parallel results)
Agent 4: { description, prompt, subagent_type }  # foreground, waits

Step 3: Worktree Isolation (when agents modify files)

Agent: {
  description: "Implement auth module",
  prompt: "...",
  isolation: "worktree",
  run_in_background: true
}

When to use worktree:

• Multiple agents editing files concurrently
• Risky changes that might need to be discarded
• Feature branch per agent strategy

When NOT to use worktree:

• Read-only research/analysis agents
• Agents that only create NEW files in different directories
• Sequential agents (no concurrent file access)

Step 4: Choosing Subagent Types

Task	subagent_type	model
Implementation	general-purpose	(default)
Code review	code-reviewer	(default)
Security audit	security-reviewer	(default)
Architecture	architect	opus
Build fix	build-error-resolver	(default)
Codebase exploration	Explore	(default)
Planning	Plan	(default)
Documentation	doc-updater	(default)
TDD	tdd-guide	(default)

Step 5: Result Synthesis

After all agents complete:

1. Collect outputs from each agent
2. Check for conflicts (same files modified, contradictory recommendations)
3. Resolve conflicts (prefer reviewer feedback over raw implementation)
4. Integrate results into coherent deliverable
5. Run final verification (build, tests, lint)

---

Communication Patterns

Lead-to-Agent (initial prompt)

Include in every agent prompt:

• Interface contract (shared identifiers, data shapes, naming conventions)
• Specific task scope (what to do)
• Boundary constraints (what NOT to touch)
• Output format expectation
• File paths relevant to their task
• Context they need but cannot discover alone

Agent-to-Lead (results)

Agent results arrive via:

• run_in_background: true -- notification when complete
• Foreground -- blocks until result returns
• Worktree -- returns branch name with changes

Agent-to-Agent (via SendMessage)

Continue a previously spawned agent:

SendMessage: {
  to: "agent-id-or-name",
  message: "Additional context or follow-up instruction"
}

Use this for:

• Providing results from one agent to another
• Asking a reviewer to re-check after fixes
• Iterative refinement loops

---

Anti-Patterns

1. Too Many Agents

Problem: More than 5 agents create coordination overhead that exceeds parallelism gains. Fix: 3-4 agents is the sweet spot. Merge small tasks into one agent.

2. Shared File Contention

Problem: Multiple agents editing the same file causes merge conflicts. Fix: Assign file ownership -- each file belongs to exactly one agent. Use worktrees if overlap is unavoidable.

3. Missing Interface Contract

Problem: Agents independently choose names, identifiers, and data shapes. At integration, nothing connects. Example: one agent creates functions expecting userId, another passes user_id. One uses class .btn-primary, another targets #submit-button. Fix: Define the shared contract (identifiers, types, naming conventions) BEFORE spawning agents. Include the contract in every agent's prompt.

4. Vague Specifications

Problem: Agents interpret ambiguous prompts differently, producing inconsistent results. Fix: Write precise prompts with explicit boundaries, file paths, and expected output format.

5. No Reviewer

Problem: Parallel implementation without quality gate produces integration bugs. Fix: Always include a reviewer agent as the final step. The Lead should verify integration points before declaring done.

6. Premature Parallelization

Problem: Parallelizing tasks that have hidden dependencies. Fix: Map dependencies first. Only parallelize truly independent tasks.

7. Fire-and-Forget

Problem: Spawning agents without monitoring or synthesizing results. Fix: Track each agent's status. Synthesize and verify before declaring done.

---

Quick-Start Templates

Template A: Feature Implementation

Task: [Feature description]

I will orchestrate this as an agent team:

1. Planning Agent (foreground, sequential):
   - Analyze requirements
   - Identify files to modify
   - Create implementation plan
   - Assign file ownership per agent

2. Implementation Agents (background, parallel, worktree):
   - Agent A: [Module 1] -- files: [list]
   - Agent B: [Module 2] -- files: [list]
   - Agent C: [Tests] -- files: [list]

3. Review Agent (foreground, sequential):
   - Review all changes
   - Check integration points
   - Verify tests pass
   - Report issues

4. Integration (lead):
   - Merge worktree branches
   - Run full test suite
   - Final verification

Template B: Codebase Analysis

Task: [Analysis goal]

1. Research Agents (background, parallel):
   - Agent A: Explore [area 1], report findings
   - Agent B: Explore [area 2], report findings
   - Agent C: Explore [area 3], report findings

2. Synthesis (lead, foreground):
   - Combine findings
   - Identify patterns and conflicts
   - Generate consolidated report

Template C: Pre-Release Review

Task: Review changes before release

1. Review Agents (background, parallel):
   - Agent A: code-reviewer -- code quality, patterns
   - Agent B: security-reviewer -- vulnerabilities, secrets
   - Agent C: Explore -- dependency audit, breaking changes

2. Report (lead, foreground):
   - Aggregate all findings
   - Prioritize by severity
   - Generate release readiness report

Template D: Refactoring

Task: Refactor [target]

1. Analysis Agent (foreground):
   - Map all usages of target
   - Identify safe refactoring boundaries
   - Create change plan

2. Implementation Agents (background, parallel, worktree):
   - Agent A: Refactor [component group 1]
   - Agent B: Refactor [component group 2]
   - Agent C: Update all tests

3. Verification Agent (foreground):
   - Build passes
   - All tests green
   - No regressions

---

Cost and Performance Considerations

Metric	Single Agent	Agent Team (3+1)
Context tokens	1x	~4x
Wall clock time	1x	~0.4-0.6x
API cost	1x	~3x

Use agent teams when time savings justify the cost multiplier. For tasks under 5 minutes single-agent, the overhead of team coordination likely exceeds the time saved.

---

Permissions Management

Multiple agents amplify permission request overhead. Before spawning teams:

1. Review .claude/settings.local.json for allowedTools
2. Pre-approve common operations agents will need (Read, Write, Edit, Bash, Glob, Grep)
3. Never use --dangerously-skip-permissions
4. Consider that each agent may trigger separate permission prompts

---

Checklist Before Launching Agent Team

• Task can be decomposed into 2-5 independent subtasks
• Each subtask has clear input, output, and boundaries
• Interface contract defined (shared identifiers, data shapes, naming conventions)
• Contract included in every agent's prompt
• No hidden dependencies between parallel subtasks
• File ownership assigned (no two agents editing same file)
• Worktree isolation configured for file-modifying agents
• Reviewer agent included as final quality gate
• Prompts are specific with explicit file paths and output format
• Cost/time tradeoff justifies team approach