الوكلاء الفرعيّون

As your tasks get more complex, Claude Code's context window fills up. Reading 20 files, analyzing dependencies, running tests — all of that context accumulates. Subagents solve this by giving each subtask its own isolated Claude instance.

Why context isolation matters

When you ask Claude Code to do something complex — say, "refactor the auth system and update all the tests" — everything it reads to understand auth takes up context that the test-updating part also needs room for. Eventually, the conversation gets so long that Claude starts losing track of earlier details.

Subagents fix this. Each one gets:

• Its own fresh context window (no previous conversation noise)
• A focused task description (not the full conversation history)
• Its own result that comes back to the parent as a concise summary

Think of it like delegating to a colleague. You brief them on one specific thing, they go do it, and they come back with the result. They don't need to know everything you've been working on.

How subagents work in practice

Claude Code spawns subagents via the Agent tool. You don't need to call it directly — when Claude decides a subtask benefits from isolation, it launches one automatically. But you can also request it:

> Research how the auth middleware works in this project.
  Use a subagent so we don't pollute our current context.

Claude will:

1. Spawn a new agent with a clear task description
2. The subagent reads files, searches code, and builds understanding
3. The subagent returns a concise summary to the parent
4. Your main conversation stays clean

Foreground vs background

Foreground subagents block until they finish — useful when the parent needs the result before continuing. Example: "Research how this function works, then refactor it."

Background subagents run asynchronously. You get a notification when they complete. Example: "In the background, audit all API routes for missing authentication." While that runs, you keep working in the main conversation.

> In the background, check every API route in src/app/api/ for missing
  auth middleware. Report which routes are unprotected.

You'll see a notification when it finishes, and you can review the findings without having interrupted your current work.

Worktrees: safe parallel file editing

When a subagent needs to edit files (not just read them), Claude Code can use git worktrees — isolated copies of your repository. This prevents the subagent's changes from conflicting with your own work or with other subagents.

The worktree is automatically cleaned up if the agent makes no changes. If it does make changes, you get the branch name so you can review and merge.

When to use subagents

Good for subagents	Keep inline
Research tasks ("how does X work?")	Quick file reads
Independent code reviews	Small edits to one file
Parallel refactors on unrelated files	Sequential dependent changes
Long-running audits (security, a11y)	Anything needing previous context
Tasks you want to continue during	Tasks where the result drives the next step

What's next

In the final lesson, you'll put everything together — files, shell, skills, MCPs, and subagents — into a production workflow for shipping real features with Claude Code.