LLM Wiki — Synaptic Lattice

Claude Code Subagents

Properties1
tagsprompt-engineering, architecture-pattern, tool-origin

Leitura de 4 min

Claude Code Subagents

Definition

Custom subagents in Claude Code: markdown files with YAML frontmatter whose body becomes the subagent’s system prompt, running in an isolated context window. The primary context-isolation mechanism for keeping verbose work out of the main conversation (captured from code.claude.com/docs/en/sub-agents, 2026-07-31).

Key Points

  • Context isolation is the core purpose — each subagent runs in its own context window with its own system prompt, tools, and permissions; “Running tests, fetching documentation, or processing log files can consume significant context. By delegating these to a subagent, the verbose output stays in the subagent’s context while only the relevant summary returns.”
  • A subagent is a Markdown file — YAML frontmatter (config) + body (system prompt); only name and description required; “Subagents receive only this system prompt plus basic environment details like the working directory, not the full Claude Code system prompt.” 15+ optional fields: tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, effort, background, isolation, color.
  • Five scopes with strict precedence — managed settings > --agents CLI JSON > .claude/agents/ > ~/.claude/agents/ > plugin agents/; scanned recursively; same name in nested dirs resolves to the definition closest to the working directory; “identity comes only from the name frontmatter field.” Plugin agents get scoped identifiers (my-plugin:review:security) and drop hooks/mcpServers/permissionMode.
  • Model routing enables cost control — model accepts aliases/full IDs/inherit (default); resolution order env var → per-invocation → frontmatter → main conversation, all checked against org availableModels allowlist; “Control costs by routing tasks to faster, cheaper models like Haiku.”
  • Capability control — tools is an allowlist, disallowedTools a denylist (deny applied first), MCP server-level patterns (mcp__<server>); background subagent (default as of v2.1.198) reduced to a ~19-tool built-in set; AskUserQuestion, EnterPlanMode, EndConversation always removed; zero-tools is an error since v2.1.208.
  • Prompt-level orchestration can sit above native subagents — the gauntlet-loop transcript describes a user-facing prompt pattern where the main agent fans out many subagents and pairs each with a critic. That makes subagents visible as a design primitive for prompt authors, not just a configuration feature for tool builders.

Worked Example — retrieval-reviewer (2026-04-24)

A field report instantiates the frontmatter-plus-system-prompt pattern with a domain reviewer: name: retrieval-reviewer, a description that triggers proactive invocation before PRs touching retrieval code, a narrow tools allowlist (read access plus scoped git diff and pytest bash), and model: sonnet so the main loop keeps the expensive model while the reviewer runs cheaply. The body scopes review to services/retrieval/** plus tests and orders a five-item checklist: chunking contract (512/64 target, single chunker entry point), reranker interface with top-k cap ≤ 50, citation-id provenance (every Chunk carries an id from the single factory function — hand-rolled ids flagged), no network calls in unit tests, and eval-snapshot regeneration in the same commit. Output contract: one Verdict line (pass / needs-changes / blocker), findings as file-path plus one-line fix, no unrelated refactors. In the replayed session the reviewer returns a hard blocker (hand-rolled UUID on line 42 violating the path-scoped rule, plus a missing integration-test marker), the agent fixes both, and only then does parallel work begin.

Implications: this is the page’s capability-control and cost-routing guidance made concrete — the allowlist plus model downshift is the copyable template for any team reviewer, and the verdict-plus-one-line-fix output contract keeps the returned summary short enough to preserve the context-isolation win. Write a custom subagent when a task repeats, needs tool restrictions, or needs a system prompt that conflicts with the main configuration.

Implications

Subagents are the vault’s canonical context-isolation pattern: they implement the “verbose output stays in the worker’s window” principle that token-usage-reduction prescribes and that the paper shows naive compression fails to achieve (evidence is deferred, not destroyed). The name-based identity + scope precedence is multi-file-agent-architecture instantiated concretely. Cost routing (Haiku for background work) is a model-selection lever orthogonal to context management. The gauntlet-loop example extends this by showing how a prompt can explicitly require worker/critic subagent pairs and a bar-to-hit loop as part of the output contract.

Open Questions

  • Heavily version-sensitive (v2.1.198 / v2.1.212 / v2.1.217 / v2.1.219 gates): Explore model inheritance, /agents wizard removal, spawn depth (5→1→3), limits (200/session v2.1.212+, 20 concurrent v2.1.217+), background-by-default (v2.1.198+), Task→Agent rename (v2.1.63), /fork→/subtask (v2.1.212).
  • Fork-vs-fresh cache behavior and how returned results/many parallel subagents still consume main context — open question shared with claude-code-sessions.

claude-code-environment-variables — CLAUDE_CODE_SUBAGENT_MODEL, _MAX_SUBAGENTS_PER_SESSION, _MAX_CONCURRENT_SUBAGENTS, _MAX_SUBAGENT_SPAWN_DEPTH claude-code-memory — memory frontmatter gives persistent agent-memory/ dirs claude-code-system-prompt — subagents get only their own body prompt, not the full system prompt token-usage-reduction — context-isolation token savings with parallel-subagent caveats multi-file-agent-architecture — distributed per-scope markdown config concrete instantiation claude-code-parallel-agents — where subagents fit among parallelization approaches gauntlet-loop-prompting — user-facing workflow pattern that explicitly pairs worker and critic subagents

Sources

  • raw/external/code-claude-com-sub-agents-5d62f063.md
  • raw/prompts/articles/robonuggets-gauntlet-loop-youtube-transcript.md
  • raw/external/freedium-mirror-cfd-i-spent-6-months-tuning-claude-code-here-a23e1587.md

Visão de gráfico

Backlinks