Claude Code Subagents Guide

01

What are subagents?

Specialised AI workers with focused responsibilities

Subagents are specialised Claude Code instances that run in their own context window. Each one has a specific job, specific tools, and specific instructions.

The mental model

Claude Code is the project manager. Subagents are specialists on the team. The manager delegates clearly-worded tasks, the specialists do focused work, and results come back without cluttering the main conversation.

They're defined as markdown files with YAML frontmatter. Put them in ~/.claude/agents/ for global access, or .claude/agents/ for project-specific agents.

02

Why bother?

Benefits of the subagent approach

Context preservation

Heavy research or exploration tasks eat tokens. Offloading to a subagent keeps your primary conversation lean. The subagent does the digging, returns the relevant findings, and the intermediate noise stays out of your main thread.

Parallelisation

Run multiple subagents simultaneously on different parts of a codebase. Review, refactor analysis, and documentation can happen concurrently.

Consistency

A well-defined subagent follows the same process every time. Your "code reviewer" applies the same standards whether you're working on Python scripts or Android apps.

Tool restriction

Subagents can be limited to specific tools. A "doc-reviewer" might only have Read and Grep access—it can analyse but never accidentally modify files.

Worth noting

Subagents burn through your usage faster. Running parallel agents on a Pro plan will hit limits quickly. Max subscription or API billing is more practical for heavy use.

03

Setting up global subagents

Create agents available across all projects

Create the directory

Global agents live in your home directory.

Code

mkdir -p ~/.claude/agents

Verify they're available

Run /agents in Claude Code to see your available subagents.

Code

~/.claude/
└── agents/
    ├── codebase-reviewer.md
    ├── doc-updater.md
    ├── refactor-advisor.md
    ├── python-specialist.md
    └── prototype-architect.md

04

Recommended starter agents

Essential agents for most workflows

These cover the most common recurring tasks. Start with two or three, refine based on what actually helps.

codebase-reviewer

Reviews code structure, identifies issues, and suggests improvements without making changes. Read-only access keeps it safe for exploration.

Use when: Starting any project, understanding unfamiliar code, pre-refactor assessment

doc-updater

Updates and creates documentation—README files, ARCHITECTURE.md, inline comments, API docs. Focuses on accuracy and clarity over comprehensiveness.

Use when: After changes, onboarding future-you, before sharing code

refactor-advisor

Analyses code for refactoring opportunities without making changes. Provides specific recommendations with effort/impact ratings. Think before act.

Use when: Technical debt assessment, before major feature work

python-specialist

Python-specific patterns, best practices, testing, type hints, packaging. Knows the ecosystem (pytest, black, mypy, poetry).

Use when: Python scripts, automation tools, data processing

prototype-architect

Breaks complex prototype work into smaller, manageable chunks. Maintains ARCHITECTURE.md to speed up future changes. Addresses the "Claude Code is slow on complex prototypes" problem by front-loading structure.

Use when: Figma Make prototypes, complex React apps, before any large change

android-specialist

Kotlin/Android patterns, Jetpack Compose, XML layouts, Gradle configuration. Knows Material Design 3 and Android-specific accessibility requirements.

Use when: Android app development, Kotlin code review

05

How to use them

Invoking and controlling subagents

Explicit invocation

Tell Claude Code to use a specific subagent:

Code

"Use the codebase-reviewer subagent to analyse this project"

"Run the doc-updater to refresh the README after these changes"

"Have the refactor-advisor look at the authentication module"

Automatic invocation

If your subagent's description field is clear enough, Claude Code may invoke it automatically when the task matches. Writing good descriptions matters:

Code

# Good - specific trigger conditions
description: Use PROACTIVELY when starting a new project or when code changes might impact architecture.

# Less good - vague
description: Reviews code and provides feedback.

Parallel execution

Request multiple subagents at once:

Code

"Explore this codebase using 3 parallel tasks:
- codebase-reviewer on /src
- doc-updater to audit existing documentation
- refactor-advisor on the utils directory"

06

Tips and gotchas

Practical advice from real usage

Start narrow

Begin with 2-3 agents. See what actually helps before building a library of 20 specialists you never use.

Tool restrictions matter

A subagent with tools: Read, Grep, Glob can analyse but not modify. This is intentional—review agents shouldn't accidentally "fix" things.

Code

# Read-only (safe for exploration)
tools: Read, Grep, Glob

# Can modify files
tools: Read, Write, Grep, Glob

# Full access including shell
tools: Read, Write, Bash, Grep, Glob

Project-level overrides

Put a subagent with the same name in .claude/agents/ to override the global version for that project. Useful when a Python project needs different standards than your Android apps.

The review bottleneck

Running 5 agents in parallel sounds productive until you have 5 sets of changes to review. The bottleneck is your attention, not Claude's speed. Parallelise research and read-only analysis freely; be more conservative with parallel modification tasks.

Cost awareness

Each subagent consumes tokens independently. A "quick" parallel exploration across 4 directories might burn through more usage than a careful sequential review. Match the approach to the task.

07

Full agent file examples

Copy and adapt these for your own use

Copy these as starting points. Refine the instructions based on what works for your projects.

codebase-reviewer.md

Code

---
name: codebase-reviewer
description: Reviews code structure and identifies issues. Use when starting a project, understanding unfamiliar code, or before major changes.
tools: Read, Grep, Glob
---

You are a code architecture analyst. Review codebases and provide actionable insights.

## Approach
1. Start with the entry point and project structure
2. Identify patterns in use (architecture, naming, organisation)
3. Flag issues with specific file:line references
4. Prioritise findings by impact

## Output
- **Summary**: One paragraph overview
- **Structure**: How the code is organised
- **Issues**: Specific problems found
- **Recommendations**: Prioritised improvements

## Constraints
- Do not modify files
- Do not give vague feedback
- Always reference specific locations

doc-updater.md

Code

---
name: doc-updater
description: Updates and creates documentation. Use after code changes or when documentation is outdated.
tools: Read, Write, Grep, Glob
---

You are a documentation specialist. Keep docs accurate, clear, and useful.

## Priorities
1. Accuracy over comprehensiveness
2. Examples over explanations
3. Keep it scannable

## Standard files
- README.md: Setup, usage, key decisions
- ARCHITECTURE.md: Structure, patterns, file purposes
- Inline comments: Why, not what

## Style
- Short sentences
- Code examples for anything non-obvious
- No marketing language
- Update dates when modifying docs

prototype-architect.md

Code

---
name: prototype-architect
description: Breaks complex prototype work into smaller chunks and maintains ARCHITECTURE.md. Use before making changes to complex React/Figma Make prototypes.
tools: Read, Write, Grep, Glob
---

You help manage complex prototype codebases by maintaining clear documentation and breaking work into manageable pieces.

## Before any change
1. Check if ARCHITECTURE.md exists and is current
2. If not, create it mapping: components, routes, state, styles
3. Identify which files the requested change will touch
4. Confirm scope before proceeding

## ARCHITECTURE.md structure
- **Components**: What each does, where it lives
- **State**: How data flows
- **Styles**: Theme, tokens, patterns in use
- **Patterns**: Conventions to follow

## Approach to changes
- Reference ARCHITECTURE.md first
- Make targeted changes only
- Update ARCHITECTURE.md if structure changes
- No unnecessary refactoring