How to Use Claude Code Subagents

How to Use Claude Code Subagents

Claude Code subagents let you split engineering work into smaller, specialized assistants inside your development workflow. Instead of asking one general agent to inspect tests, review architecture, write migration notes, and edit files in the same context, you can define focused subagents with clear responsibilities.

For AI engineering teams, this matters because LLM coding workflows become harder to debug as they grow. A broad coding agent may pass tests for the wrong reason, miss repo conventions, overwrite unrelated files, or hide important assumptions inside a long chat. Subagents give you a cleaner way to separate tasks such as test writing, code review, migration planning, and prompt-related changes.

Use subagents when you want repeatable behavior for a specific engineering task. Avoid creating them as vague “senior engineer” personas. A good subagent has a narrow job, limited tool access, clear inputs, and an expected output format.

What Claude Code subagents are

A Claude Code subagent is a named assistant with its own instructions and, optionally, its own allowed tools. You can define subagents at the project level or user level, then ask Claude Code to call them during a session.

In practice, a subagent definition usually answers four questions:

• What task does this agent own? Example: write missing tests for changed code.
• When should Claude Code use it? Example: after a feature branch changes application logic.
• What files or commands can it access? Example: read source files and run test commands, but avoid deployment scripts.
• What should it return? Example: a test plan, edited test files, and a list of assumptions.

Subagents are especially useful when your team already has repeatable workflows. If you ask the same review questions every day, or if every migration needs the same checklist, a subagent can turn that pattern into a reusable development primitive.

Where subagents fit in an AI engineering workflow

Claude Code subagents work best as task specialists. They should make engineering work easier to inspect, not harder to trust.

Common subagent roles include:

• Test-writer subagent: Finds missing test cases, writes unit tests, runs a targeted test command, and reports uncovered edge cases.
• Code-review subagent: Reviews a diff for correctness, security issues, maintainability, and repo-specific conventions.
• Migration-planner subagent: Reads schema, API, or framework changes and produces a step-by-step migration plan before any edits happen.
• Prompt-review subagent: Checks prompt changes for regressions, unclear instructions, missing examples, and evaluation gaps.
• Docs-update subagent: Updates README sections, API references, or internal docs after code changes.

If you are connecting Claude Code work to prompt management, evals, and observability, you can use PromptLayer’s Claude Code integration to keep AI-assisted changes closer to the rest of your LLM engineering workflow.

Step 1: Choose one narrow subagent use case

Start with one job that has a clear done state. Do not begin with a broad “backend engineer” or “AI architect” subagent. Those tend to overlap with the main Claude Code session and create confusion about who should do what.

Good first subagent candidates:

• “Write tests for changed files in this pull request.”
• “Review this diff for security and data handling risks.”
• “Plan a migration from one API version to another.”
• “Check prompt changes against our evaluation checklist.”

Weak subagent candidates:

• “Improve the codebase.”
• “Act as a senior full-stack engineer.”
• “Handle all refactors.”
• “Ship this feature end to end.”

The narrower the role, the easier it is to test, review, and improve.

Step 2: Create a project-level subagent

For team workflows, store subagents in your repository so they can be reviewed and versioned with the codebase. A common pattern is to keep project subagents under a Claude configuration directory, such as:

.claude/agents/
  test-writer.md
  code-reviewer.md
  migration-planner.md

You can also create or manage agents from inside Claude Code using its agent management commands. For production teams, prefer files in the repo for shared agents because they support code review, pull requests, and history.

Example: test-writer subagent

---
name: test-writer
description: Use this agent when code changes need new or updated tests. It should inspect changed files, identify missing coverage, write focused tests, and run the smallest relevant test command.
tools:
  - Read
  - Grep
  - Glob
  - Edit
  - Bash
---

You are a test-writing specialist for this repository.

Your job:
1. Inspect the changed files and nearby existing tests.
2. Identify behavior that needs test coverage.
3. Add or update focused tests.
4. Run the smallest relevant test command.
5. Report what you changed, what passed, and what remains untested.

Rules:
- Prefer existing test patterns over introducing new libraries.
- Do not rewrite production code unless the user explicitly asks.
- Do not run broad or destructive commands.
- If a test cannot be written because behavior is unclear, state the assumption before editing.
- If tests fail, report the failure and stop instead of hiding it.

This subagent has a clear job. It can read files, search the repo, edit tests, and run commands. It should not deploy, change infrastructure, or rewrite large parts of the application.

Example: code-review subagent

---
name: code-reviewer
description: Use this agent to review a diff before merge. It should focus on correctness, security, data handling, test coverage, and maintainability.
tools:
  - Read
  - Grep
  - Glob
  - Bash
---

You are a code-review specialist.

Review the current diff and return findings in this format:

## Summary
One short paragraph describing the change.

## Blocking issues
- List issues that should block merge.
- Include file paths and concrete reasoning.

## Non-blocking suggestions
- List improvements that are useful but not required.

## Test coverage
- State what appears covered.
- State what is missing.
- Recommend specific tests if needed.

Rules:
- Do not edit files.
- Do not approve changes without checking tests.
- Do not assume intent. If behavior is unclear, ask for clarification.
- Prefer specific findings over broad style comments.

This agent is read-oriented. It can inspect code and run safe commands, but it does not edit files. That keeps review separate from implementation.

Example: migration-planner subagent

---
name: migration-planner
description: Use this agent before a framework, schema, SDK, model, or API migration. It should produce a plan before implementation begins.
tools:
  - Read
  - Grep
  - Glob
---

You are a migration-planning specialist.

Create a migration plan for the requested change.

Return:
1. Current usage map
2. Required code changes
3. Required prompt or configuration changes
4. Test plan
5. Rollback plan
6. Risks and open questions

Rules:
- Do not edit files.
- Do not guess hidden business rules.
- Include exact files or directories when possible.
- Call out assumptions separately.
- Keep the plan small enough to implement in reviewable pull requests.

This subagent is useful before high-risk changes, such as replacing an LLM SDK, moving prompts into a managed registry, changing model providers, or updating database schema behavior used by an agent.

Step 3: Invoke the subagent explicitly

Claude Code may select a subagent based on its description, but explicit invocation is better when you are setting up a new workflow. It removes ambiguity and makes the run easier to inspect.

Example invocation for a test-writer subagent:

Use the test-writer subagent to inspect the current diff, add missing tests for the changed behavior, and run the smallest relevant test command. Do not modify production code.

Example invocation for a code-review subagent:

Use the code-reviewer subagent to review the current branch against main. Focus on correctness, security, data handling, and missing tests. Do not edit files.

Example invocation for a migration-planner subagent:

Use the migration-planner subagent to plan the move from our current OpenAI SDK usage to the new Responses API. Identify files, risks, test coverage, and a rollback plan. Do not edit files yet.

Keep the invocation short, but include the boundary conditions. “Do not edit files” or “do not modify production code” is often the difference between a useful specialist and a messy branch.

Step 4: Give each subagent the minimum repo access it needs

Tool access is one of the most important design choices. A subagent that only reviews code should not have write access. A migration planner should not run deployment commands. A test writer may need edit access, but usually only for test files.

Use this as a starting point:

• Read-only reviewer: Read, search, and maybe run safe inspection commands.
• Test writer: Read, search, edit test files, and run targeted test commands.
• Migration planner: Read and search only.
• Docs updater: Read, search, and edit documentation files.

Be careful with broad shell access. If a subagent can run arbitrary commands, it can run expensive tests, modify generated files, touch secrets, or trigger side effects. If your repo has scripts that deploy, publish packages, reset databases, or rotate credentials, make those boundaries explicit in the agent instructions.

Step 5: Add output formats that match review workflows

Subagents are easier to trust when their outputs are structured. Ask for file paths, commands run, test results, assumptions, and open questions.

For example, a test-writer subagent should end with:

## Changes made
- tests/api/billing.test.ts: added coverage for failed invoice retries

## Commands run
- npm test -- tests/api/billing.test.ts

## Result
- Passed: 12 tests

## Assumptions
- Retry behavior should stop after 3 failed attempts

## Gaps
- No integration test for payment provider timeout because local test credentials are unavailable

This format helps reviewers quickly decide whether the agent did the right work. It also gives your team data to turn into future eval cases.

Step 6: Evaluate your subagents

Do not treat a subagent as reliable because it produced one good result. Test it against real tasks from your repo.

Create a small evaluation set with 10 to 20 examples. For a test-writer subagent, include cases like:

• A simple pure function change that needs one new unit test.
• A bug fix where a regression test should fail before the fix and pass after.
• A UI change where the right test is a component test, not a snapshot update.
• A change that should not require tests, where the correct answer is to explain why.
• A flaky test scenario where the agent should avoid hiding the problem.

Score each run with clear criteria:

• Correctness: Did it test the right behavior?
• Minimality: Did it avoid unrelated edits?
• Repo fit: Did it follow existing patterns?
• Safety: Did it avoid risky commands and files?
• Transparency: Did it state assumptions and results clearly?

If you manage prompts and agent instructions in PromptLayer, store these subagent definitions as versioned prompt artifacts or linked engineering assets. That gives your team a record of what changed when subagent behavior changes.

Before and after: replacing one broad agent with three focused subagents

Here is a common setup that causes problems:

Use Claude to implement the billing retry feature, update tests, review the code, update docs, and prepare the migration plan.

This puts too much responsibility into one long context. The agent may start editing before it understands the migration risk. It may review its own code too gently. It may update docs based on behavior that later changes.

A better flow splits the work:

1. Migration-planner subagent: Reads the current billing flow and creates a plan.
2. Main Claude Code session: Implements the planned code changes.
3. Test-writer subagent: Adds focused tests and runs targeted commands.
4. Code-reviewer subagent: Reviews the final diff without editing files.
5. Main Claude Code session: Applies accepted fixes and prepares the pull request.

This gives each step a clearer purpose. It also creates natural checkpoints where an engineer can review the plan, inspect the tests, and decide whether the branch is ready.

Common mistakes to avoid

Creating broad, overlapping subagents

If you have a “backend-engineer” subagent, a “senior-reviewer” subagent, and a “refactor-agent” subagent, they may all try to own the same task. This creates noisy handoffs and inconsistent behavior.

Prefer roles with hard boundaries. “Reviews diffs and never edits files” is better than “improves backend quality.”

Giving agents too much repo access

Many subagents do not need write access. Some do not need shell access. Start with the smallest useful tool set and expand only when you see a real need.

For example, a migration planner can produce a high-quality plan with read and search tools. It does not need to edit files or run scripts.

Skipping evals

A subagent is a prompt-driven workflow. You should evaluate it like any other LLM workflow. Run it against known examples, compare outputs, and track regressions when you edit its instructions.

If a code-review subagent misses an auth bypass once, turn that case into an eval. Do not rely on memory or hope that the next instruction change fixes it.

Relying on hidden assumptions

Subagents often fail when they assume repo conventions that were never written down. If your tests require a specific factory pattern, say so. If migrations must be backward compatible for 30 days, put that in the migration-planner instructions.

Good instructions reduce guessing. They also make reviews faster because the expected behavior is visible.

Not versioning prompts and agent definitions

Subagent instructions change over time. If you do not version them, you cannot explain why behavior changed between two pull requests.

Store project subagents in your repo. Review changes to agent definitions like you review application code. For teams running more formal LLM workflows, track prompt versions, eval results, and production behavior in the same release process.

Treating subagents as autonomous production deployers

Subagents should not deploy production changes on their own. They can plan, edit, test, and review within controlled boundaries. Production release steps need explicit approval, audit trails, and rollback plans.

This is especially important for LLM applications, where a small prompt or retrieval change can alter user-facing behavior without changing much code.

Recommended screenshots and examples to include

If you are documenting this workflow for your team, include screenshots or short recordings for the steps engineers repeat most often:

• Claude Code subagent setup: Show where the subagent file lives in the repo, such as .claude/agents/test-writer.md.
• Sample subagent definition: Show the frontmatter, description, tool list, and task instructions.
• Invocation flow: Show a developer explicitly asking Claude Code to use the test-writer or code-reviewer subagent.
• Before and after: Show a broad one-shot request, then the same workflow split into planner, implementer, tester, and reviewer steps.
• Review output: Show the subagent returning file paths, commands run, test results, assumptions, and open questions.

These examples reduce onboarding time. They also help your team spot when someone is using a subagent outside its intended scope.

A practical subagent rollout plan

For an engineering team, a safe rollout can be simple:

1. Week 1: Add one read-only code-review subagent. Test it on 10 recent pull requests.
2. Week 2: Add a test-writer subagent with limited edit permissions. Use it on low-risk branches.
3. Week 3: Add a migration-planner subagent for one upcoming SDK, schema, or prompt migration.
4. Week 4: Review outputs, collect failures, update instructions, and create a small eval set.

Do not measure success by how much code the subagents generate. Measure whether they reduce missed tests, catch real review issues, produce clearer plans, and avoid unrelated edits.

Final checklist

• Give each subagent one clear responsibility.
• Store shared subagents in the repo.
• Use explicit invocation while the workflow is new.
• Limit tools and repo access.
• Require structured outputs.
• State assumptions and open questions.
• Run evals on real examples.
• Version agent definitions and prompt changes.
• Keep production deployment under explicit engineering control.

Claude Code subagents work best when you treat them as small, testable parts of your engineering system. Start narrow, inspect the outputs, and improve the instructions with the same care you apply to code.

PromptLayer helps AI teams manage prompts, evals, datasets, and observability for LLM applications and agent workflows. If you are building repeatable Claude Code workflows or tracking prompt behavior across your team, create a PromptLayer account at https://dashboard.promptlayer.com/create-account.