Guides

Claude Code subagents: setup and three useful examples

A subagent is a separate Claude instance with its own context window, system prompt and tool list. The main conversation hands it a task and gets back a summary. That's ideal for noisy work like running test suites, and for getting an independent second opinion.

Defining a subagent

Create a Markdown file in .claude/agents/ (project) or ~/.claude/agents/ (personal):

---
name: code-reviewer
description: Independent, skeptical reviewer for a diff. Use proactively after
  finishing a non-trivial change, or when the user asks for a review.
tools: Read, Grep, Glob, Bash
---

You are a senior engineer reviewing code you did not write...

• name and description are required. As with skills, the description decides when Claude delegates. Words like "use proactively" encourage automatic use.
• tools is a comma-separated allowlist. Leave out Edit and Write for reviewers so they can't "fix" things behind your back.
• model can be haiku, sonnet, opus or a full model ID. Use a cheaper, faster model for mechanical work.

Run /agents in Claude Code to create or edit subagents interactively.

Example 1: a skeptical code reviewer

The key instruction: verify each suspected issue before reporting it, and say so plainly if you find nothing. Without it, review agents pad their reports with speculative nitpicks. Order the checks by what matters: correctness, then security, data integrity, API breaks and tests, with style last. Finish with a verdict: "Ready to merge", "Merge after fixes" or "Needs rework".

Example 2: a test runner on Haiku

---
name: test-runner
description: Runs the project's tests, lint and type checks and returns a concise
  diagnosis of failures instead of raw logs. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: haiku
---

Discover commands from CLAUDE.md, package.json, Makefile or CI config. Never guess.
Run them, and for each failure read the test and the code under test, then classify:
real bug | test outdated | flaky (re-run once) | pre-existing.
Report: commands run, pass/fail counts, then per failure: test, file:line,
cause (1–2 sentences), classification, suggested fix. At most ~15 lines of log each.

Thousands of lines of test output stay in the subagent's context instead of filling yours.

Example 3: a security auditor

Have it follow data from entry points (handlers, CLI args, queue consumers) to sinks (SQL, shell, templates, file paths, outbound fetches). For every finding, require a source → sink trace and a realistic exploit scenario. That requirement alone removes most false positives. Checklist areas: authorization on every object (IDOR), injection, XSS, CSRF, SSRF, path traversal, secrets in code and logs, weak crypto, and unsafe deserialization.

When not to use a subagent

Subagents start with a fresh context, so they're poor at tasks that depend on details from your current conversation. Use them for self-contained jobs with a clear input and a summarizable output.