Subagents Everywhere: How to Split a Big Task Across Specialized Agents

When one agent tries to do everything — read the whole codebase, write the feature, test it, security-review it — its context window fills with noise and its performance degrades. Subagents solve this by delegating chunks of work to specialized agents that each run in their own context and report back a summary. Per the Gemini CLI documentation, subagents operate alongside the primary session with "their own set of tools, MCP servers, system instructions, and context window," and the point is to "keep the primary agent focused on the overall goal, decision making, and final response."

Why subagents exist: context is the constraint

The Claude Code best-practices docs put the underlying problem plainly: "Claude's context window holds your entire conversation, including every message, every file Claude reads, and every command output," and "LLM performance degrades as context fills." When the main agent reads dozens of files to investigate a bug, all of that lands in its context. A subagent does the reading in a separate window and returns only the findings, so the main conversation stays clean. That is the whole mechanism: subagents are a context-management tool first, a parallelism tool second.

How you define a subagent

Both major tools use the same shape: a Markdown file with YAML frontmatter naming the agent, its tools, and its system instructions.

Gemini CLI. Per the docs, subagents live as .md files at three levels: personal (~/.gemini/agents/), project (.gemini/agents/, shared with the team), or bundled in an extension's agents/ directory. A definition looks like:

name: frontend-specialist
tools: [read_file, grep_search, glob, list_directory, web_fetch, google_web_search]
model: inherit

followed by the system instructions. Gemini ships three built-ins: generalist (all tools, good for "batch refactoring or running commands with high-volume output"), cli_help, and codebase_investigator (exploration and "bug root-cause analysis"). You delegate explicitly with @agent syntax — @frontend-specialist Can you review our app and flag potential improvements? — and list configured agents with /agents.

Claude Code. Subagents live in .claude/agents/ with the same frontmatter pattern. A security reviewer, for example:

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for injection
vulnerabilities, auth flaws, secrets in code, and insecure data handling.

You invoke them by telling the agent to: "Use a subagent to review this code for security issues." The docs highlight two killer uses: investigation (reading many files without cluttering your main context) and adversarial review, where a reviewer subagent "sees only the diff and the criteria you give it, not the reasoning that produced the change, so it evaluates the result on its own terms."

A practical roster of specialized agents

• Research / investigator — explores the codebase and reports back, keeping file reads out of your main context.
• Test agent — writes and runs tests, where verbose output stays in the subagent's window.
• Security reviewer — scoped to Read/Grep/Glob/Bash, looks only at the diff for vulnerabilities.
• Frontend specialist — UI components, accessibility, design adherence.
• Refactor agent — mechanical, high-volume changes across many files (Gemini's generalist is built for this).

When to parallelize — and when not to

Subagents can run in parallel: Gemini CLI supports "parallel subagents," and you can ask it to "run the frontend-specialist on each package in parallel." But the docs are equally clear about the costs.

Parallelize when the work is independent and read-heavy — investigating several modules, running the same analysis across many packages, or fanning a migration across files that do not touch each other. Independent, non-overlapping work is where parallel subagents shine.

Do not parallelize when agents would edit the same code simultaneously. Gemini's docs warn that parallel execution "risks code conflicts when multiple agents edit simultaneously." It also has a direct cost: parallel runs "will also lead to usage limits being hit faster," and Claude Code's docs note that agent teams "use approximately 7x more tokens than standard sessions" when teammates run in plan mode, because each maintains its own context window. So parallelism is a tradeoff: faster wall-clock time, more tokens, and a conflict risk if the work overlaps.

The rule of thumb: split a task across subagents when the pieces are genuinely separable and at least one is read-heavy; keep editing of shared code sequential; and remember that every parallel agent is another full context window burning tokens.

Read: Vibe Coding in 2026 — From Prompts to Autonomous Agents

FAQ

What is a subagent?

A specialized agent that runs alongside your main session with its own tools, MCP servers, instructions and context window. It does a focused job and returns a summary, keeping the primary agent focused on the overall goal.

How do I create one?

Add a Markdown file with YAML frontmatter — name, tools, optional model, then system instructions — to .gemini/agents/ (Gemini CLI) or .claude/agents/ (Claude Code), at project or personal scope.

When does parallelizing subagents waste resources?

When agents edit the same code (conflict risk) or when the task is small enough that the overhead and extra token cost outweigh the speedup. Parallelism shines on independent, read-heavy work.

Why use a subagent instead of just one big prompt?

Because one agent's context fills with file reads and command output, degrading performance. A subagent does that work in a separate window and returns only findings, keeping your main context clean.

Bottom line

Subagents are first a context-management tool — they keep file reads and verbose output out of your main conversation — and second a way to parallelize. Define them as small Markdown files with scoped tools (research, test, security, frontend, refactor), delegate explicitly, and parallelize only when the work is independent and read-heavy. Keep edits to shared code sequential, and budget tokens: every parallel agent is another full context window.

Sources and further reading