Field SOP
Field SOP

Claude Code Subagents: A Five-Step SOP for Cheaper AI Coding

A hands-on SOP for Claude Code subagents (basis: October 8, 2026; pairs with the site's Haiku 5.5 hotspot): from the /agents command to a parallel fleet of specialized workers. File locations and priority: .claude/agents/ (project) overrides ~/.claude/agents/ (user); a markdown file with YAML frontmatter is all it takes. Fields covered one by one: name (lowercase-hyphen), description (drives auto-delegation - learn to write Use PROACTIVELY / MUST BE USED trigger phrases), tools (omitted means inherit-all; least privilege says list them explicitly), model (sonnet/opus/haiku/inherit; default sonnet), permissionMode, skills (not inherited from parent), and hooks (PreToolUse/PostToolUse/Stop; once unsupported). Model routing: search/summarize/classify/extract to haiku, multi-file changes to sonnet, architecture to opus (community-sourced per-task cost comparison $0.03/$0.24/$1.20, labeled single-source). Isolation: subagents run in their own context and return only summaries; they cannot spawn subagents (no Task tool); implementation stays with the main agent (Anthropic's own guidance). Haiku 5.5 tie-in: model: haiku picks up the new model, and Claude Code v2.1.292 adds an effort parameter on the Agent tool plus claude plugin install --marketplace (release-note caliber). Four copy-ready skeletons (code-reviewer/security-reviewer/debugger/test-writer) and four failure patterns to avoid.

Published October 8, 20269 min read
<!-- claude-code-subagent-sop | sop | Claude Code Subagents: A Five-Step SOP for Cheaper AI Coding -->

Claude Code subagents are separate AI workers you define inside Claude Code, each with its own context window, toolset, and model. Set up correctly, they search, summarize, and classify at a fraction of what your main context costs; set up wrong, they waste tokens, overlap with the main agent, or stall on tasks they were never meant to do. On October 8, 2026, the timing for a proper SOP is unusually good: the Claude Haiku 5.5 launch one day earlier made the cheapest model in the family dramatically better, and the latest Claude Code release added cost controls that plug directly into subagent definitions.

This SOP walks six steps, from a one-minute availability check to the failure modes that fill GitHub issues. Each step ends with an expected result so you can verify before moving on. If you want a parallel hands-on for a different model provider, our DeepSeek-V4-Pro on Claude Code SOP covers swapping the backend with two environment variables - that one changes what model Claude Code talks to, this one changes how Claude Code organizes its work. And if you are still deciding which coding tool deserves your budget at all, the free AI coding credits comparison puts the mainstream options side by side.


Step 0: Align on Availability

A subagent is only as cheap as the plan it runs on, so confirm three things before writing any config.

  1. Check your Claude Code version. Two features in this SOP - the Agent-tool effort parameter and the plugin marketplace install flag - arrived in v2.1.292 per the October 7 release notes. Older builds will silently ignore both.
text
claude --version
  1. Confirm your access tier. Subagents work on Claude Pro and Max subscriptions as well as API-key setups, but the model routing in Step 3 only pays off when you can actually call Haiku-class models. If you run Claude Code against a third-party backend, verify that backend honors the model field - otherwise every subagent quietly runs on the same model.

  2. Skim the built-in agents. Claude Code ships with three ready-made ones: Explore (read-only search on Haiku, with Quick, Medium, and Very thorough levels), Plan (gathers context before plan mode), and General-purpose (Sonnet with all tools). You may not need to write anything at all if a built-in already covers the job.

Expected result: you know your version number, you know which billing tier you are on, and you can name the three built-in agents without opening the docs. If your version is below v2.1.292, upgrade now so the Step 4 features exist when you reach them.


Step 1: Create Your First Subagent with /agents

Claude Code stores subagents as markdown files with YAML frontmatter. There are two locations, and the priority order matters:

  • Project level: .claude/agents/ inside your repository. These take precedence and can be committed so the whole team shares them.
  • User level: ~/.claude/agents/ in your home directory. These apply to every project you open and are ideal for personal workflow agents.

When both define the same name, the project-level file wins. Run the interactive manager:

text
/agents

You get four options: Create, Edit, Delete, and View. Choose Create and let Claude generate the initial definition - it interviews you about the agent's purpose and writes the file. Then press e to open it in your editor and refine by hand. The generated draft is a starting point; the frontmatter fields in the next step are where quality is decided.

Save the file under .claude/agents/ for anything project-specific. Commit it. A subagent definition is exactly the kind of tribal knowledge that evaporates when a teammate asks "how did you automate that review?"

Expected result: a new markdown file exists under .claude/agents/, /agents lists it, and the file opens cleanly in your editor with a YAML block at the top and a system prompt below.


Step 2: Fill Every Frontmatter Field Deliberately

Each field changes runtime behavior, so go through them one by one rather than accepting the defaults. Here is a working code-reviewer definition we will reference throughout:

yaml
---
name: code-reviewer
description: Reviews code changes for quality and consistency. Use PROACTIVELY after writing or modifying code. MUST BE USED before any commit.
tools: Read, Grep, Glob, Bash
model: haiku
permissionMode: default
---

name - lowercase with hyphens. This is the handle the main agent and teammates use to address the subagent, so keep it short and descriptive.

description - the single most important field. It decides when Claude Code automatically delegates to this agent. Write it with explicit trigger phrases: Use PROACTIVELY for should-fire-without-asking behavior, MUST BE USED for hard requirements. A vague description like "helps with code" means the agent never gets picked.

tools - the allowlist. Omit it and the subagent inherits every tool, which violates least privilege and makes the agent slower to reason about. A reviewer that can read and search but not write files cannot break anything.

model - one of sonnet, opus, haiku, or inherit (matching whatever the main session uses). Omit it and the default is sonnet. This field is the lever for everything in Step 3 and Step 4.

permissionMode - default, acceptEdits, or bypassPermissions. Use default for anything that touches your codebase; reserve bypassPermissions for sandboxed read-only agents where you have verified the tool list.

skills - which skill packages the agent loads. Note that skills are not inherited from the parent session; if your agent needs one, list it here explicitly.

hooks - optional PreToolUse, PostToolUse, and Stop hooks for automation around the agent's tool calls. Note that one-time hooks are not supported here.

Expected result: your subagent file has every field above filled with a deliberate value, the name is lowercase-hyphenated, and the description contains at least one explicit trigger phrase.


Step 3: Route Models by Task Shape

The routing strategy that dominates community production setups is simple: default to Haiku for subagents unless the task requires reasoning. Haiku handles lookup, summarization, classification, and extraction. Sonnet handles multi-file changes and debugging. Opus handles architecture decisions that get revisited rarely but shape everything downstream.

A widely shared third-party comparison illustrates the spread on a representative research task - these are single-source community numbers, not official benchmarks, so treat them as magnitudes:

Agent modelTimeCostOutput quality rating
Haiku~8 seconds~$0.03~60%
Sonnet~45 seconds~$0.24~85%
Opus~2 minutes~$1.20~95%

Read the table as a routing rule, not a scoreboard: a 40x cost gap between the cheapest and priciest option means the wrong default is expensive at scale. If you fan out five search subagents per session and each runs on Opus out of laziness, you have spent more on lookups than on the actual implementation. When your main session runs on a heavier model, the inherit option keeps subagents consistent with it - use it when you cannot articulate why a subagent needs something different.

For the boundary cases, ask one question: does this task need judgment across many files, or retrieval within a known scope? Retrieval is Haiku territory. Judgment is Sonnet. Judgment that redefines the project is Opus, and it probably belongs in the main agent anyway, which is the discipline Step 5 formalizes.

Expected result: every subagent you own now declares an intentional model - Haiku for find-and-summarize agents, Sonnet for edit-and-debug agents, and no unexamined defaults left.


Step 4: Pair with Claude Haiku 5.5 and the New Effort Knob

This is where the SOP connects to the batch's hotspot. The model field above does not pin a specific release - fill in haiku and Claude Code resolves it to the latest Haiku, which since October 7 is Haiku 5.5. That matters because the Haiku 5.5 release details show pricing at $0.10 per million input tokens and $0.50 per million output on the under-100K tier, a 1M-token context (up from 200K), and - per Anthropic's own published benchmarks - large jumps on terminal and agentic evaluations versus Haiku 4.5. In plain terms: the search-and-summarize agents from Step 3 just got dramatically more capable at the same routing slot, and the wide context window means a single Explore-style agent can swallow big file listings without spilling.

Two Claude Code features from the v2.1.292 release notes sharpen the pairing. First, the Agent tool accepts an effort parameter, so a subagent can run at a reduced effort level when a task is easy and at full effort when it is hard - within one request you trade cost against intelligence, which is precisely the decision Step 3 makes per agent. Second, plugin distribution got easier: claude plugin install --marketplace lets you pull packaged agents and skills from a marketplace instead of hand-copying files, which is how team conventions spread.

If your routing also uses Sonnet for the heavy subagents, note the simultaneous change on that side: Sonnet 5.5's cache-read price halved to $0.10 per million, which Anthropic says cuts costs about 20% for most agentic workloads. For teams budgeting across providers, our coding-tool credits comparison shows where subscription credits and API pricing intersect.

Expected result: a Haiku-routed subagent in your project completes a real search task, and you can see in the session cost display that it spent cents, not dollars. If you set an effort level, confirm the agent respects it on an easy query.


Step 5: Avoid the Four Classic Failures

The recurring failure reports in Claude Code's GitHub issues cluster into four patterns. Each has a one-line fix.

Failure 1: using subagents for implementation. Subagents cannot spawn further subagents - the Task tool is not passed to them - and their results come back as a summary, not as live working state. Anthropic's own guidance, echoed by engineer Adam Wolf, is that subagents are best at looking things up and returning short summaries. Implementation that mutates many files belongs in the main agent, where you can course-correct mid-stream. Fix: restrict subagent purposes to research, review, and verification.

Failure 2: vague descriptions. An agent described as "a helpful assistant" is never auto-selected, because delegation matching runs on the description text. Fix: rewrite descriptions with explicit trigger phrases per Step 2, then test that delegation actually fires.

Failure 3: tools-wide-open. Inheriting every tool makes agents slower, riskier, and harder to debug. Fix: allowlist per purpose - a test-writer needs test runners and file read access, not your deployment hooks.

Failure 4: re-briefing tax. Every subagent starts with zero context, so if you delegate twenty small interleaved tasks, you pay the project briefing twenty times. Community reports describe sessions burning hundreds of thousands of tokens on repeated context this way. Fix: batch related lookups into one subagent call with a thorough brief, and keep chatty iteration in the main agent.

Expected result: an audit of your subagent definitions shows no implementation-assigned subagents, no vague descriptions, no unbounded tool lists, and delegation patterns that batch related work.


FAQ

Q1: Where exactly do subagent files live, and which location wins on conflict?

A1: Project-level files go in the .claude/agents/ directory of your repository, user-level files in the agents folder under your home directory. When both define the same agent name, the project-level definition takes precedence. Commit the project-level ones so your whole team inherits the same roster.

Q2: What happens if I omit the tools field?

A2: The subagent inherits every tool available to the main session. That is convenient but against least-privilege practice - the agent can do more than its job requires, and the broader surface makes behavior harder to predict. Always declare an explicit allowlist for production agents.

Q3: Which model should a new subagent use by default?

A3: The community production answer is Haiku unless the task requires reasoning. Lookups, summaries, classification, and extraction run fine on Haiku and cost an order of magnitude less; reach for Sonnet when the agent edits multiple files or debugs, and reserve Opus for architectural judgment, which usually belongs in the main agent anyway.

Q4: Do subagents share context with the main conversation?

A4: No. Each subagent runs in its own independent context window, like a fork of the project view. It returns only a summary to the main thread, which keeps the main context clean - but it also means the subagent knows nothing from your conversation unless you put it in the prompt, and it cannot recursively launch other subagents.

Q5: How does the new effort parameter interact with model routing?

A5: Routing (Step 3) picks the model per subagent; the effort parameter, added to the Agent tool in Claude Code v2.1.292, then tunes how hard that model works within a request. Together they let a cheap Haiku agent run at minimal effort for trivial lookups while the same definition can be called with higher effort when the task deserves it.

This article is AI-assisted and human-edited. Last updated: 2026-10-08

FAQ

Where exactly do subagent files live, and which location wins on conflict?
Project-level files go in the .claude/agents/ directory of your repository, user-level files in the agents folder under your home directory. When both define the same agent name, the project-level definition takes precedence. Commit the project-level ones so your whole team inherits the same roster.
What happens if I omit the tools field?
The subagent inherits every tool available to the main session. That is convenient but against least-privilege practice - the agent can do more than its job requires, and the broader surface makes behavior harder to predict. Always declare an explicit allowlist for production agents.
Which model should a new subagent use by default?
The community production answer is Haiku unless the task requires reasoning. Lookups, summaries, classification, and extraction run fine on Haiku and cost an order of magnitude less; reach for Sonnet when the agent edits multiple files or debugs, and reserve Opus for architectural judgment, which usually belongs in the main agent anyway.
Do subagents share context with the main conversation?
No. Each subagent runs in its own independent context window, like a fork of the project view. It returns only a summary to the main thread, which keeps the main context clean - but it also means the subagent knows nothing from your conversation unless you put it in the prompt, and it cannot recursively launch other subagents.
How does the new effort parameter interact with model routing?
Routing (Step 3) picks the model per subagent; the effort parameter, added to the Agent tool in Claude Code v2.1.292, then tunes how hard that model works within a request. Together they let a cheap Haiku agent run at minimal effort for trivial lookups while the same definition can be called with higher effort when the task deserves it.

Related

Field SOP

Build a Game Without Code: A 49-Agent AI Studio

Turn a single Claude Code session into a 49-agent game studio with Claude Code Game Studios (github.com/Donchitos/Claude-Code-Game-Studios, MIT, about 33,837 stars): three-tier directors/leads/specialists, 72 slash commands, and 12 hooks that catch hardcoded values and accidental pushes, with a protocol that keeps every decision in your hands. Includes a five-minute setup, a demo-trimmed workflow, third-party API options, and a fit checklist.

Nov 3, 20269 min read
Field SOP

Claude Code Sandboxing: Install It Without Giving Agents Root

Give your agent a sandbox, not root: a hands-on install guide for Anthropic's open-source sandboxing tool srt (anthropics/sandbox-runtime, Apache-2.0, 6,615 stars, repo created October 2025). Verbatim npm global install, the ~/.srt-settings.json config verbatim, platform primitive differences across macOS/Linux/Windows with three default-policy tiers, and the three-layer Windows truth stated as-is: the srt CLI is still Alpha, Schannel is a hard limitation with no workaround, and Claude Code on native Windows does not run the sandbox — use WSL2. The 84 percent interception rate is the official self-reported figure; an eight-item community pitfall list included (#139/#160/#122 fixed, Ubuntu 24.04 sysctl, and more).

Oct 26, 202611 min read
Field SOP

Claude Code DeepSeek Setup: Nine Env Vars, No Old Tutorials

A hands-on SOP for wiring Claude Code straight into DeepSeek, with every command and variable taken from the official guide (api-docs.deepseek.com/quick_start/agent_integrations/claude_code), reflecting the current configuration after the 1017 checkpoint. Primary search phrase: "Claude Code DeepSeek setup" (S1=3/S2=1/S3=2/S4=3). Migration path with nine environment variables: ANTHROPIC_BASE_URL to https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN with your DeepSeek API key, ANTHROPIC_MODEL=deepseek-flash[1m], DEFAULT_OPUS and DEFAULT_SONNET also deepseek-flash[1m], DEFAULT_HAIKU=deepseek-flash, CLAUDE_CODE_SUBAGENT_MODEL=deepseek-flash, CLAUDE_CODE_EFFORT_LEVEL=max, CLAUDE_CODE_AUTO_COMPACT_WINDOW=786432; both PowerShell and Linux/Mac variants are given. Install from scratch in four steps: Node.js 18+ (plus Git for Windows on Windows), npm install -g @anthropic-ai/claude-code, verify with claude --version, set the variables and run claude in your project directory. Model mapping: requests starting with claude-opus route to deepseek-v4-pro (billed at V4 Pro prices, pricier than Flash - a must-read reminder), claude-haiku and claude-sonnet route to deepseek-flash. Web Search works natively but bills on two lines: search requests per the Search API plus extra token costs for summarizing retrieved content. Pricing (official rate page): off-peak 0.15 dollars per million input tokens on cache miss, 0.003 on a hit (one fiftieth of the miss price), 0.60 output; peak (weekdays 01:00-04:00 and 06:00-10:00 UTC) doubles everything; weekends and Chinese public holidays count as off-peak. Five pitfalls: AUTH_TOKEN and API_KEY are not the same thing (mixing them equals no config), old and new variables coexisting can cause auth conflicts (keep only the new ones, per community guides), never commit keys via settings.json (persist them in ~/.bashrc, ~/.zshrc or system environment variables), validate the tool-calling chain with a minimal read-one-file-then-edit-one-file task before real work, and check the live model with /status. Older tutorials still reference retired names like deepseek-chat. Division of labor: deepseek-v4-pro-claude-code-sop is the V4-Pro-0813-era two-variable minimal setup (2026-09), while this piece is the full current official configuration after 1017; for the Harness itself see deepseek-harness-quickstart-sop.

Oct 19, 202610 min read