07 — Subagents — Isolated Expert Bubbles for Focused Work

"Just more agents" described subagents without explaining why they exist. The reason is context hygiene: a subagent is an isolated context bubble with its own system prompt and restricted tools, that handles a focused task and returns a summary — so the main conversation stays clean. [1] The whole point is context hygiene: the verbose research and intermediate logs live in the bubble, not in my primary thread.

The framing that clicked is to think of subagents as a context-management technique, not a parallelism feature (parallelism is a separate benefit, covered in the scaling post). The main agent has one context window, and it fills up. When a task involves reading twenty files to find one fact, the _reading_ shouldn't pollute the main thread — only the _fact_ should come back. A subagent is the bubble that does the reading in its own clean window and returns just the conclusion [1][2].

What a subagent actually is

The roadmap's definition is precise: a specialized AI assistant that functions as an independent team member to handle a focused task on behalf of the main agent [1]. Three properties matter:

• Its own isolated context window. It starts with a clean slate. Whatever it reads, runs, or generates stays in its bubble.
• A tailored system prompt. Defined by a markdown file in .claude/agents/ with YAML frontmatter specifying its name, description, model, and a restricted set of tools [3].
• A summary return. When it finishes, it hands back a summary to the main agent — not the full transcript. The main thread stays lean.

Creating a subagent

The recipe is a markdown file in .claude/agents/ with YAML frontmatter [3]. The frontmatter pins the four things that define the bubble:

• name — what the main agent calls on.
• description — when it should be invoked (the discovery trigger, same idea as a skill's).
• model — which model powers it. A common pattern is a cheaper/faster model (Haiku) for a scan-the-logs subagent, the strong model (Opus) for an architecture-planning one.
• tools — the restricted set. This is the safety lever: a "research only" subagent gets Read and Grep but not Edit or Bash, so it literally cannot change anything.

The /agents command manages them inside a session, and the roadmap frames it as the transition from a single-assistant model to a multi-agent workflow — delegating security auditing, unit testing, or architectural planning to specialists with isolated windows and tailored prompts [4].

Why this is a context technique

The reason subagents are more than a curiosity is the context math. The main agent re-reads its entire conversation every turn (that's how it maintains state). If I let it read twenty files inline, those file contents sit in the context for the rest of the session, inflating every subsequent turn's token cost and accelerating context rot. If instead a subagent reads those twenty files in its own window and returns a three-line summary, the main thread carries three lines — not twenty files [2].

The roadmap states this directly: subagents are an architectural tool that manages the context window by practicing "selective attention," keeping the main conversation lean while specialized tasks remain high-precision [2]. The pattern I reach for: any task whose _inputs_ are large but whose _conclusion_ is small is a subagent candidate. "Find the bug," "audit these logs," "summarize this dependency" — large reads, small answers.

The slash commands around them

A few commands live in the subagent orbit:

• /agents — create, configure, orchestrate subagents; switches to a multi-agent workflow [4].
• /context — a diagnostic grid showing how the model's context window is currently allocated: every file, turn, and tool result, and which consume tokens [5]. My check before deciding to delegate.
• /compact — summarizes the conversation to free context (an alternative when I don't want to spawn a subagent) [6].
• /init and /memory — covered in the CLAUDE.md post; they shape the persistent memory the main agent (and any subagent) starts from.

The way of thinking: /context tells me _when_ to delegate, /agents is _how_, and the subagent's restricted tools frontmatter is _how much rope_ the delegate gets.

How I use this

The habit these notes left me with is a delegation test on every large-read task. Before I let the main agent read a directory or a long log, I ask: do I need the file contents later, or just the conclusion? If just the conclusion, it goes to a subagent with a tight tool restriction. Research subagents get Read + Grep (no edits possible); planning subagents get the strong model and read-only tools. The main thread stays short, costs stay predictable, and the one thing I lose — seeing the intermediate steps — is exactly the thing I didn't want cluttering the conversation anyway.

References

[1] Anthropic, "Create custom subagents," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/sub-agents

[2] Anthropic, "Claude Code Subagents: Complete Guide to Multi-Agent Architecture," 2025. [Online]. Available: https://wmedia.es/en/writing/claude-code-subagents-guide-ai

[3] Anthropic, "Create custom subagents — agent file format," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/sub-agents

[4] Anthropic, "Interactive mode — /agents," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/interactive-mode

[5] Anthropic, "Interactive mode — /context," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/interactive-mode

[6] Anthropic, "Interactive mode — /compact," Claude Code Docs, 2025. [Online]. Available: https://code.claude.com/docs/en/interactive-mode