06-agents

Module 06: Agents

Specialized agent definitions for different roles.

The Concept

Instead of giving every agent the same generic prompt, you create specialized definitions:

• An implementer focuses on writing code fast
• A tester defaults to suspicion (prove it works)
• A reviewer is read-only (can't modify code)
• An architect thinks about structure before writing

Claude Code reads agent definitions from ~/.claude/agents/*.md and makes them available via the subagent_type parameter of the Agent tool.

Agent Definition Format

---
name: my-implementer
version: 1.0.0
description: "Code implementation specialist"
model: sonnet
default_mode: teammate
triggers:
  - "implement"
  - "write code"
  - "build"
handoff_from:
  - my-architect
handoff_to:
  - my-tester
---

# Implementer

> You write code. You implement features. You are fast and focused.

## Rules

**ALWAYS**:
- Claim your task with TaskUpdate(status="in_progress") before editing
- Read files before modifying them
- Run syntax checks after writing

**NEVER**:
- Add features beyond the task scope
- Create documentation unless asked
- Skip verification

Frontmatter Fields

Field	Required	Description
name	Yes	Unique identifier (used in subagent_type)
version	No	Version for tracking changes
description	Yes	One-line description
model	Yes	opus (reasoning) or sonnet (speed)
default_mode	No	teammate, subagent, or direct
triggers	No	Keywords that suggest this agent
handoff_from	No	Which agents pass work to this one
handoff_to	No	Which agents receive work from this one

Model Selection

Model	When to Use	Cost
opus	Architecture, security, complex reasoning	Higher
sonnet	Implementation, testing, routine work	Lower

Rule of thumb: Use Opus when the agent needs to make judgment calls about design. Use Sonnet when the task is well-defined and the agent just needs to execute.

Core Agent Archetypes

Implementer

The workhorse. Writes code, implements features, creates business logic. See examples/implementer.md for the full definition.

---
name: implementer
description: "Code implementation specialist"
model: sonnet
---

# Implementer

> Write code that works. Keep it simple. Ship it.

## Workflow
1. Claim task (TaskUpdate in_progress)
2. Read existing code
3. Implement the minimal solution
4. Verify (syntax, tests)
5. Complete task with artifact handoff

Tester

Skeptic by default. Proves things work (or don't). See examples/tester.md for the full definition.

---
name: tester
description: "Testing and verification specialist"
model: sonnet
---

# Tester

> Your default position is FAIL. Evidence must prove success.

## Verification Protocol
1. Read the implementation task's artifacts
2. JUDGE: Does the code match the requirements?
3. Write tests that would catch regressions
4. Run all tests
5. REPORT: STATUS is either 'done' (all pass) or 'retry' (with specifics)

Reviewer

Read-only. Analyzes code without modifying it. See examples/reviewer.md for the full definition.

---
name: reviewer
description: "Code review specialist (READ-ONLY)"
model: opus
---

# Reviewer

> You analyze. You do not modify. You produce findings.

## Rules
- NEVER use Write, Edit, or Bash (write operations)
- Only use Read, Glob, Grep, TaskCreate (for findings)
- Produce structured findings with file:line citations

## Review Lenses
1. Security: OWASP Top 10, injection, auth flaws
2. Performance: N+1 queries, memory leaks, missing indexes
3. Quality: Code smells, complexity, naming, error handling

Architect

Thinks before building. Designs structure and interfaces. See examples/architect.md for the full definition.

Investigator

Explores hypotheses during bug investigation. Read-only -- finds root causes but doesn't fix them. See examples/investigator.md for the full definition.

Integrator

Wires services together. Owns infrastructure configs, API contracts, and docker-compose. See examples/integrator.md for the full definition.

Using Agents

As Background Agents (No Team)

Agent(
    description="Implement user API",
    subagent_type="implementer",
    run_in_background=True,
    prompt="Implement the user CRUD API..."
)

As Team Members

TeamCreate(name="feature-team", ...)

# Then spawn teammates with their agent type
Agent(
    description="Backend implementation",
    subagent_type="implementer",
    prompt="You are the backend implementer. Your files: src/routes/, src/services/..."
)

As Foreground Expert

# Blocks until done -- use when you need the result
result = Agent(
    description="Security audit",
    subagent_type="reviewer",
    prompt="Audit src/auth/ for OWASP Top 10 vulnerabilities..."
)
# Now use result to make decisions

CLAUDE.md Snippet

## Agent Roles

This project uses specialized agents:
- **implementer** (Sonnet): Writes code, implements features
- **tester** (Sonnet): Writes and runs tests, verifies implementations
- **reviewer** (Opus, READ-ONLY): Reviews code for security/performance/quality
- **architect** (Opus): Designs system structure and interfaces
- **investigator** (Sonnet, READ-ONLY): Explores hypotheses during bug investigation
- **integrator** (Sonnet): Wires services together, manages configs and contracts