# Agent Team

> Coordinate Claude Code agent teams with bounded tasks, clear ownership, and integration evidence. Use when independent work benefits from parallel agents.

- Skill: `cskwork/agent-team` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add cskwork/agent-team`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cskwork/agent-team/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cskwork (https://skillmd.com/u/cskwork)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cskwork/agent-team

---


# 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 생성 시 |

## Before Assembling a Team

Derive this context from the request and repository. Ask only for material unresolved scope or integration decisions:

### 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
- Independent subtasks would reduce elapsed time or investigation rework
- 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)
- 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)

Inspect the **context type** and choose only the research needed to decompose the task. Reuse existing evidence; a separate intelligence team is optional, not a prerequisite.

**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 use authoritative documentation and relevant working examples. Popularity is not correctness evidence; findings must support the interface decisions this task actually needs.

**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**: inspect the affected path and callers, then reuse adequate existing context. Familiar technology does not establish current code behavior.

---

### 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 parallel implementation touches a shared boundary, define the **shared interface** the affected 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:

```markdown
# 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)

```markdown
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 using the code, requirements, and runtime evidence; a reviewer’s role does not make its claim correct.
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:
```markdown
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**: Coordination and duplicated context can outweigh parallelism.
**Fix**: Use the fewest agents that cover independent useful work, within the user’s budget and available capacity.

### 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**: Verify integration points and use a separate reviewer when the risk warrants one. Do not equate a reviewer’s approval with passing evidence.

### 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.

---

## Task templates

For worked implementation, research, review, and refactoring dispatches, use `references/orchestrator-templates.md` and `references/team-examples.md` only when the task needs them. Examples illustrate topology; their agent counts, commits, and tool choices do not expand the user’s authorization.

## Cost and Performance Considerations

Measure the actual tradeoff: duplicated context, coordination work, elapsed time, and verification quality. Report cached input, uncached input, and output separately when measured; do not infer a fixed cost or speed multiplier from agent count.

## Permissions Management

Multiple agents amplify permission request overhead. Before spawning teams:

1. Review `.claude/settings.local.json` for `allowedTools`
2. Give each agent only the tools and paths authorized for its task; do not broaden permission settings merely to avoid prompts.
3. Never use `--dangerously-skip-permissions`
4. Consider that each agent may trigger separate permission prompts

---

## Checklist Before Launching Agent Team

- [ ] Each delegated task is independently useful
- [ ] 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
- [ ] Integration verification assigned; independent reviewer included when warranted
- [ ] Prompts are specific with explicit file paths and output format
- [ ] Cost/time tradeoff justifies team approach