10 Practical Claude Code Subagent Use Cases With Examples

Useful Claude Code subagent use cases include reviewing code, investigating bugs, planning tests, and explaining unfamiliar projects. The best starting point is a task with a clear question and a result you can check.

A subagent is a helper that does a focused job for your main Claude session. This article suggests ten roles you could give that helper. These are workflow ideas, not a ranking of downloadable products or official built-in agent names.

If you have never created one, follow the complete Claude Code subagent setup guide first. It includes a copy-paste agent file and a practice task.

Which Claude Code subagent should you create first?

Choose the problem you repeatedly face:

Your problem	Suggested helper	Useful result
You inherited an unfamiliar app	Code explainer	A short map of one feature
You want a second look at a change	Code reviewer	Findings with file and line references
A bug is hard to locate	Debugging investigator	Evidence and the next check to run
You are unsure what to test	Test planner	Specific inputs and expected results
A change touches sensitive access	Security reviewer	Possible issues to verify
Setup instructions confuse new teammates	Documentation reviewer	Missing or incorrect steps
You need to connect an external API	API researcher	A sourced integration plan
A database query needs review	Query reviewer	Correctness and performance questions
You want to simplify difficult code	Refactoring planner	Small changes and their risks
A build produces pages of errors	Log analyst	The first relevant failure and evidence

Anthropic recommends custom subagents for repeated, focused work with reusable instructions and restricted tools. Its guide to using subagents also warns against defining too many overlapping helpers.

You can use the prompts below to request a focused subagent without first creating ten custom files. If a task proves useful repeatedly, turn its instructions into a named agent.

1. Code explainer: understand one feature

Use it when: you open a project and cannot tell how a feature works.

For example, you need to understand what happens between clicking “Sign in” and receiving a session cookie. Ask for that path, not an explanation of every file.

Use a read-only subagent to trace the login flow in this project.
Start from the login page and follow the request to the backend.
Return the main files, the order of steps, and where the session is created.
Include file references. Flag anything you cannot confirm. Do not edit files.

Good output: a short flow with supporting file paths. You should be able to open those files and follow the explanation.

Limit: unfamiliar names can lead to wrong guesses. “This file appears to handle sessions” is weaker than a reference to the actual session creation call. Ask for evidence.

2. Code reviewer: check a specific change

Use it when: you want another pass over a calculation, validation rule, or changed function.

Use a read-only subagent to review src/cart/calculate-total.js.
Discounts are percentages between 0 and 100.
Look for incorrect totals and missing edge cases.
For each finding, show an input that demonstrates the problem.
Do not edit files or run commands.

Good output: a concrete input, the wrong result, and the expected result. That is more actionable than “improve error handling.”

Limit: a review is advice. Verify each finding before changing behavior. If the helper lacks terminal access, it cannot truthfully say it ran the test suite.

The setup tutorial builds this kind of reviewer from scratch.

3. Debugging investigator: find the next useful check

Use it when: you know the symptom but not the cause.

Use a read-only subagent to investigate why valid login requests
sometimes return 401. Inspect the auth middleware and the redacted
sample log in debug/login-sample.txt.
Return confirmed observations, possible causes, and one next check
for each cause. Do not change code or contact production services.

Good output: a distinction between what the code proves and what still needs testing.

Limit: the helper may not have the running system, exact request, or complete logs. A plausible explanation is not a confirmed root cause.

Run the proposed check yourself or authorize a separate, clearly scoped test in a safe environment.

4. Test planner: turn requirements into test cases

Use it when: code exists, but you are unsure whether the tests cover the behavior.

Use a read-only subagent to inspect src/cart and its tests.
Shipping is free when the subtotal is at least 50.
List missing tests with exact inputs and expected outputs.
Include a case just below 50, exactly 50, and above 50.
Do not write files or run the suite.

Good output: specific cases you can translate into tests, including boundary values.

Limit: asking a helper to infer every requirement from the implementation can produce tests that repeat the same mistake as the code. Supply the intended rule.

You can later ask the main assistant to implement the approved tests. Keep planning and execution clear so you know what actually happened.

5. Security reviewer: inspect one sensitive path

Use it when: a change affects login, file uploads, payment permissions, or private records.

Use a read-only subagent to review the invoice download endpoint.
Check whether the signed-in user must belong to the invoice's account.
Reference the authorization checks in code.
Separate confirmed missing checks from assumptions.
Do not read credentials, test live accounts, or make network requests.

Good output: a trace from the incoming request to the ownership or membership check.

Limit: a clean answer is not a security certification. Verify with tests using separate test users and records. A helper can miss checks or misunderstand a framework.

Keep the permissions small. See protecting API keys during agent work for practical boundaries.

6. Documentation reviewer: make setup reproducible

Use it when: new teammates repeatedly get stuck following your README.

Use a read-only subagent to compare README.md with package.json
and .env.example. The example file contains no real credentials.
Find missing prerequisites, incorrect commands, and unexplained variables.
Return a revised setup section as text. Do not install dependencies
or change files. Mark commands you have not executed.

Good output: a sequence someone can follow, with prerequisites before commands and expected results after them.

Limit: reading a command is different from testing it. Have someone follow the revised instructions in a clean environment before calling them verified.

This role can also help with release notes, provided you supply the actual changes and ask it to avoid invented features.

7. API researcher: check the provider’s current rules

Use it when: an integration depends on current authentication, request formats, or pagination rules.

Use a research subagent to read the official API documentation at
[paste the provider's documentation URL].
Find the authentication method, the endpoint for listing customers,
pagination rules, and documented rate limits.
Return source links and a minimal request outline with placeholders.
Do not send API requests or use real credentials.

Replace the bracketed URL before sending the prompt.

Good output: linked evidence and clearly marked gaps. If the documentation does not specify a limit, the helper should say so.

Limit: a read-only local-file agent cannot browse just because the prompt asks it to. Use a helper with available web tools, or give it saved documentation. Do not report old local notes as newly verified information.

8. Database query reviewer: inspect before running

Use it when: a query returns duplicate rows, has unclear filters, or may be expensive.

Use a read-only subagent to review queries/monthly-revenue.sql
against schema.sql. Paid orders should be counted once, excluding refunds.
Check joins, filters, and grouping. List schema assumptions and
suggest what to inspect in an execution plan. Do not connect to a database.

Good output: possible duplicate-producing joins, missing conditions, and specific questions about indexes or data distribution.

Limit: static review cannot prove that a query is fast. Measure on representative data in an appropriate environment. Do not give a reviewer production database access just to read a SQL file.

9. Refactoring planner: break a large change into small steps

Use it when: a large file is hard to maintain, but a complete rewrite feels risky.

Use a read-only subagent to inspect src/billing/invoice-service.js.
Suggest three small refactoring steps that preserve current behavior.
For each step, name the affected functions, the risk, and the tests
needed first. Do not implement the plan.

Good output: a short sequence you can review and carry out one step at a time.

Limit: a cleaner structure can still change behavior accidentally. Add or verify the relevant tests before accepting the change.

If you later use multiple workers to edit code, assign separate responsibilities and review how their changes fit together. Avoid having several workers rewrite the same file at once.

10. Log analyst: reduce a long failure report

Use it when: a failed test run or build produces too much output to scan comfortably.

Use a read-only subagent to inspect debug/redacted-build.log.
Identify the first relevant failure and any later errors caused by it.
Quote only the necessary log lines and include line numbers.
Suggest the next diagnostic step. Do not change files or run commands.

Good output: the failure that matters, supporting lines, and a limited next step.

Limit: the earliest error is not always the root cause. The helper should explain why it considers a line relevant. Remove secrets and customer data before sharing logs.

Turn a useful role into a reusable agent

Suppose the test-planning prompt saves you time every week. Create .claude/agents/test-planner.md in your project:

---
name: test-planner
description: Suggests missing test cases for named files using the user's stated requirements. Use for test planning without edits or execution.
tools: Read, Grep, Glob
model: inherit
---

Inspect the files named in the task and their relevant existing tests.
Use the supplied requirements as the source of intended behavior.
If a requirement is missing, list the question instead of guessing.
Return a table: scenario, input, expected result, existing coverage.
Prioritize normal behavior, boundary values, and invalid inputs.
Do not edit files, run commands, or claim that tests passed.
Do not read credential files or unrelated private data.

Start Claude from that project and ask:

Use test-planner to review src/cart and its tests.
Shipping becomes free at a subtotal of 50.
Give me five test cases, with boundary cases first.

This is an original planning template. It creates suggestions, not executed tests. The official configuration reference covers the fields and supported options; the step-by-step setup guide shows where to save the file and how to check delegation.

When should you keep the task in the main conversation?

Keep a quick question or tiny edit with the main assistant when a handoff adds no value. A useful test is: can you state the helper’s job and expected result in two sentences?

“Help with my project” is too broad. “Trace this endpoint and show where account ownership is checked” is a focused task.

My suggested starting set is one reviewer and one test planner. Add more only after you notice a repeated need. Compare their findings with actual code and tests; keep the roles that produce useful, checkable results.

Common questions

Are these the best Claude Code subagents for every project?

No. They are starting ideas. A small documentation project and a payment service have different needs. Choose based on your repeated work, not the number of agents in a collection.

Can subagents write code too?

They can be configured with tools that allow changes. These examples mostly use read-only review because it makes their results easier to check before acting. Adding write or terminal tools changes what the helper can do.

Can I use them outside software development?

Yes, a similar pattern can review a document for inconsistent terms, organize research notes, or check a spreadsheet’s assumptions. Supply the right files and clear criteria. Verify facts and calculations independently.

How do I know whether a subagent helped?

Track useful findings, false alarms, time spent reviewing, and usage. A report is valuable when it helps you make a correct change or understand the system, not simply because it is long.

For more ways to organize Claude Code, read the skills and subagents comparison or browse the AI agents articles.

If your helper fails to load or run, follow Claude Code subagent not working: common problems and fixes.