Claude Code Subagents: Building Specialists for Complex Coding Tasks

A new feature sounds manageable at first: one more API, a form, and a few tests. Then Claude is suddenly deep in database models, access rights, and error messages. The conversation grows while the actual task keeps slipping into the background.

Claude Code subagents help split up work like this. One specialist examines the code, another develops test cases, a third tracks down a specific root cause. What matters is that each one gets a clear assignment and returns a verifiable result.

In this guide you'll build three of your own agent templates. You'll also learn how to scope their tasks, and when adding more agents costs more than it's worth.

What are Claude Code subagents?

Subagents are specialized AI assistants that Claude Code can delegate subtasks to. They work on those tasks in their own context window and return results to the main conversation. That helps, for example, to offload large research tasks without pulling every file Claude read into the ongoing discussion. Anthropic explicitly describes this use for research, independent subtasks, and additional reviews. ^[1]

Picture a workshop: you discuss the job with the person in charge. For electrics, mechanics, and inspection, they bring in the right specialists. For that collaboration to work, everyone needs a concrete assignment.

With AI, though, a different rule applies: a role like "security expert" is not a qualification and not proof of quality. Whether an agent was actually useful shows up in its evidence, traceable reasoning, and verified results.

When is a custom specialist agent worth it?

A reasonable rule of thumb for getting started: define an agent for a task that recurs in your project and has a clearly describable result.

You usually don't need this split for a typo fix. Tightly interwoven changes can also be easier to handle in a single conversation. Additional agents need their own context and cause extra processing, so more parallelism doesn't automatically mean lower cost. ^[1]

Subagent, skill, MCP, and CLAUDE.md: what goes where?

These building blocks complement each other but handle different jobs. The official feature overview separates project context, reusable workflows, external connections, and offloaded agent work. ^[2]

For how CLAUDE.md and AGENTS.md work together when several coding agents share the same repository, see AGENTS.md vs. CLAUDE.md: Which File Does Your AI Coding Project Need? (Read article). For a broader look at skills, plugins, apps, and MCP, see AI Skills, Plugins, Apps, and MCP: What's the Difference? (Read article).

You don't need an extra MCP connection for the following examples. An existing project and a working Claude Code setup are enough.

Building your own Claude Code subagent

1. Place the agent file in the right folder

Project-scoped agents live under .claude/agents/, and personal agents shared across several projects live under ~/.claude/agents/. Their Markdown files start with YAML metadata, followed by the working instructions. The required fields are name and description. ^[3]

Save the first template in your project as .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Reviews named source files for concrete functional bugs and missing access controls. Use for reviews after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You review the code named in the task. Respond in English.

Approach:
1. Read the named files and the directly relevant callers.
2. Check error paths, input validation, and access controls.
3. Assess each issue against a concrete trigger.
4. Separate evidenced bugs, reasoned suspicions, and open questions.

Boundaries:
- Do not modify any files.
- Do not claim to have run tests or shell commands.
- Do not invent findings or attacks you did not actually carry out.
- Do not review additional modules without a clear connection to the task.

Output per finding:
- Priority: high, medium, or low
- File and line, where clearly identifiable
- Trigger and impact
- Evidence from the code
- Smallest reasonable fix suggestion

If no solid finding exists, say so explicitly.
Close by stating the limits of this review.

This is an original example template, not the result of an actual project review. Adjust the review focus to your own application.

2. Choose the description and tools deliberately

description describes the use case. tools limits which tools are available; without it, the subagent inherits the available tools. model: sonnet selects the Sonnet model alias. ^[3]

A description like "expert in everything" barely helps with task routing. "Reviews Flask endpoints for missing tenant checks" describes a concrete responsibility instead.

For the reviewer, the listed read and search tools are enough. Its job is to explain findings. Arbitrary shell access isn't needed for that workflow.

3. Call agents explicitly

In Claude Code, use an assignment like this one, replacing the file paths with files that actually exist:

Use the code-reviewer subagent for backend/routes/orders.py
and backend/services/orders.py.

Check whether users can only read and modify orders that belong
to their own tenant. Consider direct callers and existing tests
where relevant.

Give me concrete findings with evidence. Don't change any files.

Explicit delegation in natural language is supported. If you created the agents folder only during the current session and the agent wasn't picked up, restart Claude Code. ^[3]

Version note: According to current documentation, the interactive /agents setup wizard was removed as of version 2.1.198. The agent files themselves are unaffected. Older tutorials may therefore show a different flow. ^[3]

Second template: a test planner for overlooked edge cases

A test planner is especially useful when "writing tests" has so far meant covering only the successful default case.

For an order feature, relevant questions already come up before the first test: what happens with an unknown order? Can another tenant see it? What happens if a request arrives twice?

Save this template as .claude/agents/test-planner.md:

---
name: test-planner
description: Builds a prioritized test plan from requirements and existing code. Use before implementations or to find test gaps.
tools: Read, Grep, Glob
model: sonnet
---

You plan tests for the function named in the task.
Respond in English.

Read the requirements, the implementation, and relevant existing tests.
If requirements and code contradict each other, flag the conflict.

Consider, where relevant to the task:
- The default case and empty inputs
- Invalid data types and boundary values
- Missing authentication and foreign tenants
- Repeated requests and failures of dependent services

Deliver a table with:
Priority | Test case | Setup | Input | Expected result

Mark unknown expected values as an open requirement.
Do not invent product rules or existing test coverage.
Do not write files and do not run tests.
Close by recommending the three most important tests to implement first.

Matching assignment:

Use test-planner for the order API in backend/routes/orders.py.
The business requirements are in docs/order-api.md.
Consider the tests under tests/orders/.

Produce at most ten prioritized test cases. Flag which
requirements aren't clear enough to turn into a test.

Capping the list at ten cases forces real prioritization. For a first pass, a short plan covering the important failure cases is usually easier to judge than a long list of similar variants.

Third template: a debugger with write access

In this example, a debugger is meant to reproduce and fix a bug. That gives it a different responsibility than the two read-only agents.

Save the template as .claude/agents/focused-debugger.md:

---
name: focused-debugger
description: Reproduces a concretely described bug in a local development environment and produces a small, verifiable fix.
tools: Read, Grep, Glob, Bash, Edit, Write
model: sonnet
permissionMode: default
---

You work on exactly the bug described. Respond in English.

Workflow:
1. Read the reproduction steps, relevant files, and test instructions.
2. Before running commands, check which environment and data they affect.
3. Reproduce the bug, ideally with a targeted local test.
4. Establish the cause with evidence and change only the necessary code.
5. Verify the fix and any directly affected neighboring functions.

Boundaries:
- No production access, deployments, pushes, or data migrations.
- No installing new dependencies without checking in first.
- Do not revert someone else's changes.
- Do not weaken tests just to get a green result.
- Do not output any credentials.
- If the test environment is unclear, ask before running anything.

Closing report:
- Cause and evidence
- Changed files and rationale
- Commands actually run, with results
- Checks not performed, and why
- Remaining uncertainties

Note the limit of this template: the instructions describe desired behavior. Technically enforced access rights come from permission rules and the environment. Claude Code explicitly distinguishes between prompt instructions and enforced permissions. Run /permissions to check the rules in effect. ^[4]

Bash enables program execution, and with it potentially file changes or network access too. Even a test script can delete data or call external services. So use a vetted local test environment and matching rules. permissionMode: default doesn't replace that check; existing approvals still apply. ^[4] For more on locking down credentials and API keys, see Protecting Secrets and API Keys in AI Agents: Using .env, Vault, and Permissions the Right Way (Read article).

These examples were built from the documentation but were not actually run in a Claude Code installation for this article.

Running all three specialists together

Take an example bug: when editing an order, its existence gets checked, but whether it belongs to the logged-in tenant is left unclear.

A reasonable assignment for Claude Code could look like this:

Investigate the tenant check when editing orders.

Phase 1:
Have code-reviewer check the access control, and have test-planner
derive the relevant cases from requirements and existing tests.
These two read-only tasks may run in parallel.
Give both the relevant file paths and requirements.

Phase 2:
Summarize the findings. If a concrete bug is confirmed, hand
focused-debugger the finding and the matching test cases.
It should reproduce and fix the bug in the local test environment.

Phase 3:
Have code-reviewer check the changed files again.
Report which tests actually ran and what's still open.

Here, the first two investigations can start independently of each other. The debugger, by contrast, needs their findings. The final check needs the finished fix. This order is a design suggestion for the example process, not an automatically guaranteed pipeline.

Anthropic generally recommends investigating and planning complex changes first, and verifying results through tests or other concrete evidence. ^[5]

Define "done" before you start

For this example bug, your acceptance check could look like this:

• A targeted test shows the bug before the fix.
• After the fix, the disallowed request gets rejected.
• A legitimate request still works.
• The diff contains only changes that trace back to the task.
• Any checks that weren't performed are explicitly named.

"The agent says it works" does not meet these criteria yet. A closing report should let you judge the fix yourself.

Isolated context doesn't protect you from file conflicts

When several agents are allowed to write, you should organize their work areas deliberately. Two competing changes to the same function are harder to merge than two independent analyses.

Claude Code supports this with git worktrees: separate working directories with their own branches but a shared repository history. Subagents can work with worktree isolation. ^[6]

A matching agent configuration adds this extra field:

isolation: worktree

A worktree separates files. It does not, however, separate a shared test database or external services for your project planning. Merging and reviewing the changes also remains its own task. Plan clear ownership for that.

For a first attempt, a single writing debugger is enough. Add parallel implementations only once the benefit is clear for your specific project.

Common mistakes when building your own subagents

The role describes a personality instead of a task

"You are the best developer in the world" sets neither a review scope nor a result. Instead, write which files are relevant, which question needs answering, and what evidence you expect.

Every agent gets the same broad assignment

If three agents are each asked to "optimize" the entire application, you create overlap. Split the work instead — for example, access control, test cases, and implementing a confirmed fix.

A review contains only generic advice

"Improve security" is not yet an actionable finding. Ask for a trigger, a concrete location, and the expected impact. If the reviewer can't deliver that, it should flag the point as an open question.

Too much context gets passed through unfiltered

Give a specialist the relevant files and requirements. A full chat history full of discarded ideas can needlessly obscure the current task. Precise file references and concrete success criteria also match Anthropic's recommendations for effective coding assignments. ^[5]

Agent files get adopted without review

When using someone else's template, read not just the role description but also its tools and other configuration. Check in particular whether it fits your project and the actions you want to allow.

Frequently asked questions about Claude Code subagents

Do I need to create several agents right away?

No. Start with the reviewer and check on a manageable change whether its findings actually help you. Add further roles for tasks that recur.

Can subagents change files themselves?

Yes, if their tools and the applicable permissions allow it. The first two templates are limited to reading and searching. The debugger additionally gets write and execution tools. ^[3][4]

Are several agents automatically cheaper?

No. Additional agents cause additional overhead. Whether splitting the work pays off depends on the task, the context it needs, and the benefit it actually delivers. ^[1]

Why doesn't Claude find my new agent?

Check the file location, the YAML, and the agent name. If you created the agents folder only after the session started, restart Claude Code. ^[3]

What's the best first use case?

Have the agent review a small change you already understand well. That lets you quickly judge whether it finds relevant problems, respects known requirements, and states uncertainty honestly.

Your first worthwhile use case

Create code-reviewer.md and pick a manageable function. Ask a concrete question such as: "Can users modify data belonging to a different tenant?" Then judge the evidence and the suggested fix.

That gives you a practical yardstick for further specialists: every new agent should own a recurring task and deliver a result you can review more easily. For how Claude Code stacks up against other coding agents, see Claude Code vs. OpenAI Codex: Which Coding Agent Is Better? (Read article).

You'll find more practical guides on AI, coding, and system administration on the KI-Buster blog.

Sources and further documentation

Editorial status: October 2, 2026. Primary sources: [1] Anthropic: How and when to use subagents in Claude Code — use cases and overhead; for behavior that may differ, the current reference in [3] applies. [2] Claude Code: Extend Claude Code — how project instructions, skills, subagents, MCP, and hooks differ. [3] Claude Code: Create custom subagents — file format, configuration, invocation, and version-dependent behavior. [4] Claude Code: Configure permissions — enforced access rules and permission modes. [5] Claude Code: Best practices — task assignments, planning, and verifiable results. [6] Claude Code: Run parallel sessions with worktrees — separate working directories and subagent isolation. The agent prompts and the order-API scenario are original examples; no self-measured productivity gains or completed project tests are claimed.