Subagents and Parallel Tasks

The problem subagents solve

The enemy of a long session is context pollution: 50 turns of dead ends, abandoned approaches, and irrelevant files, and the AI can no longer see what matters.

A subagent is a clean context that does one job and returns only the result, keeping the intermediate noise out of your main session.

Three typical uses

1. Broad exploration “How does auth work in this repo?” — send a subagent to read; you receive the conclusion.

2. Independent parallel work Five unrelated tasks running at once instead of queued.

3. Specialized roles Frame it as architect, reviewer, or tester to get a different lens on the same problem.

Common subagent types

Type	Strength	Limits
Exploration	Fast search across a codebase	Read-only
Planning	Designs approaches, analyzes architecture	Read-only, doesn’t execute
General	Reads, writes, runs commands	Full permissions, highest risk
Domain-specific	Spreadsheets, documents, etc.	Narrow scope

Rule: prefer read-only unless writes are actually required.

Writing subagent prompts (the key part)

A subagent cannot see your current conversation. It has none of your prior discussion, no shared assumptions, no “the thing I mentioned earlier.”

Prompts must be self-contained.

❌ "Refactor the auth module per what we discussed"

✅ "Refactor /Users/me/proj/src/auth:
    - Current: session-based storage in auth/session.ts
    - Target: JWT with a 7 day expiry
    - Constraint: don't change caller-facing signatures
    - Done: existing tests all pass
    Return a plan first. Don't edit files yet."

Write as if briefing someone who just walked into the room.

Three rules for parallel work

Rule 1: tasks must be genuinely independent Two agents editing the same file will clobber each other. Same file → sequential.

Rule 2: never delegate what you don’t understand “Fix the bug you found” — you don’t know what it found, so how do you verify? Have it report first, decide after you understand.

Rule 3: background the long ones Installs, builds, and bulk processing belong in the background. You’ll be notified when they finish.

A practical pattern

For a large refactor:

1. Exploration subagent → map the current state
2. You read the report (don’t skip this)
3. Planning subagent → propose an approach
4. You approve, possibly after a few rounds
5. General subagent → execute
6. You review the diff and run tests

You sit at every decision point; the routine work is delegated.

When not to use subagents

• Tiny tasks — overhead exceeds the benefit
• Creative work needing tight back-and-forth — isolation gets in the way
• Context that’s already clean — no benefit

Next

MCP Server Configuration.