Claude Code Patterns: Subagents, Worktrees, Orchestration Guide

Claude Code is more than a single agent typing in your terminal. Once you learn to delegate work to subagents, run parallel tasks with git worktrees, and orchestrate multi-step workflows, your productivity goes to a completely different level.

Most developers use Claude Code as a one-shot assistant: ask it a question, get an answer, repeat. That works for small tasks. But complex projects need a different approach. A codebase-wide refactor, a multi-file migration, or building a new feature with tests, docs, and deployment config all at once requires patterns that go beyond single-prompt interaction.

That is where subagents, worktrees, and orchestration come in. These three patterns let you decompose big jobs, execute pieces in parallel, and coordinate everything into a cohesive result. This guide breaks down each pattern with practical examples you can apply today.

Understanding the Three Core Patterns

Before diving into implementation details, it helps to understand what each pattern solves and when to use it. These three patterns address distinct scaling problems.

What Subagents Solve

Subagents let you spin up focused, isolated instances of Claude Code for specific subtasks. Instead of one agent juggling everything in a single context window, you delegate discrete chunks of work to specialized subagents, each with its own context and instructions.

The main benefit is context isolation. When you ask Claude Code to refactor a module AND write tests AND update documentation all at once, these tasks compete for space in the context window. The agent might lose track of the original requirements halfway through. With subagents, each one gets a clean slate focused on a single job.

What Git Worktrees Enable

Git worktrees let you check out multiple branches simultaneously in separate directories. Instead of stashing your current work, switching branches, and losing your place, you simply open a new terminal window pointed at a different worktree directory. Each worktree has its own branch checked out, and they share the same git repository underneath.

For Claude Code users, worktrees are the secret to parallel AI-assisted development. You can run one Claude Code instance working on a feature branch in one worktree while running a separate instance on a bugfix in another. The two processes never interfere with each other.

What Orchestration Ties Together

Orchestration is the pattern of coordinating multiple agents and tasks into a coherent sequence or workflow. It is the conductor layer that decides which agent handles what, in what order, and how results get combined.

Orchestration becomes critical as your workflows grow. A simple sequence (scaffold, then implement, then test) can still run as a single prompt. But once you add branching, or fan-out (run lint, type-check, and build in parallel), you need an orchestration layer to manage it.

These three patterns complement each other. Subagents handle delegation within a single worktree. Worktrees enable parallel execution across branches. Orchestration ties them together into repeatable workflows. Mastering all three gives you a complete toolkit for AI-assisted development at scale.

Setting Up Subagents in Claude Code

Subagents in Claude Code are spawned through the Task tool. When you invoke the Task tool with a specific agent definition, Claude creates a separate instance with its own system prompt, context, and scope. The subagent works independently and returns its result to the main agent when finished.

Defining Agent Types

Claude Code ships with built-in general-purpose agents, but the real power comes from defining your own agent types with specialized prompts. You can configure agents for code review, debugging, documentation writing, or any other repeated task type your team needs.

Open your project settings or the agents configuration file to define custom agent types. Each agent type needs a name, a system prompt that defines its expertise and constraints, and a list of tools it should have access to. A Review agent might only need Read and Grep tools, while a Coding agent gets Bash, Read, Write, and Edit access.

When to Spawn a Subagent

The best time to delegate to a subagent is when the task has clear boundaries and requires a different context than your main conversation. Here are the most common scenarios where subagents shine.

First, parallel research tasks. If you need to understand three different files or modules, spawn one subagent per file instead of asking the main agent to read them sequentially. Each subagent returns its findings, and you combine them. This cuts the research phase from minutes to seconds.

Second, isolated implementation tasks. When you need to implement a specific function or class while keeping the main conversation focused on architecture, delegate the implementation to a subagent. This keeps your main context clean and makes review easier, since the subagent’s output is self-contained.

Third, background tasks that might take a while. Spawn a subagent for operations that involve running builds, executing test suites, or performing large-scale searches. The main agent stays responsive and the subagent reports back when done.

Communication Between Main Agent and Subagents

Subagents communicate with the main agent through structured results. When the Task tool returns, it includes the subagent’s complete response, any files it read or wrote, and the tools it used. You can inspect this output, validate the work, and decide whether to accept the result, request changes, or spawn a follow-up subagent.

The key thing to remember is that subagent context is not visible to the main agent until the Task tool completes. You cannot peek in on an in-progress subagent. Design your delegation so each subagent has everything it needs to complete independently. If a subagent needs information it does not have, it should request it from the main agent through its response.

Using Git Worktrees for Parallel AI Development

Git worktrees solve a real pain point for anyone doing AI-assisted development: you want to work on multiple things at once, but git only lets you have one branch checked out at a time per clone. Worktrees remove that constraint entirely.

Creating and Managing Worktrees

Creating a new worktree is straightforward with the git worktree command. Run git worktree add ../project-feature feature-branch to create a new directory at the sibling path ../project-feature with the feature-branch checked out. The new worktree shares the same .git directory as your main clone, so there is no duplication.

To list all active worktrees, run git worktree list. This shows each worktree’s path, its checked-out branch, and whether it is locked or prunable. When you are done with a worktree, remove it with git worktree remove ../project-feature.

Running Claude Code in Parallel Across Worktrees

Here is the workflow that changes everything. Open three terminal windows. In the first, cd into your main worktree and run Claude Code on whatever pending review or refactoring task needs your attention. In the second, cd into a feature worktree and have Claude Code implement a new feature. In the third, cd into a bugfix worktree and have Claude Code track down and fix an issue.

Because each worktree has its own branch checked out in its own directory, the three Claude Code instances operate on completely separate copies of the codebase. They cannot step on each other’s changes. When you are ready to integrate, you merge or rebase the branches in git as normal.

This approach is particularly powerful for teams where one developer is implementing a feature while another reviews a pull request. Instead of waiting for one git operation to finish before starting the other, both happen simultaneously.

Worktree Best Practices

A few practices keep worktree-based workflows manageable. First, use a consistent naming convention for your worktree directories. Names like ../project-feature-auth or ../project-bugfix-login make it obvious which worktree is for what.

Second, clean up worktrees promptly after merging. Stale worktrees accumulate and become confusing. Get in the habit of running git worktree list at the end of each day and removing any that are no longer needed.

Third, be aware that worktrees share a single reflog and stash. Operations like rebase and bisect affect the shared git data, so be careful running destructive commands while multiple worktrees are active on the same branch family.

If you want to explore orchestration patterns for larger projects, check out our guide on advanced Claude Code orchestration and how to coordinate multi-agent workflows. And for the broader context on Claude Code development, see our complete developer guide to Claude Code skills and plugins.

Multi-Step Orchestration with Claude Code

Orchestration is the layer that coordinates multiple agents and tasks into a defined workflow. With Claude Code, orchestration can happen at several levels depending on your needs.

Sequential Workflows

The simplest orchestration pattern is a sequential workflow: Task A finishes, then Task B starts, then Task C runs. Claude Code handles this naturally when you break your work into a series of prompts. Each prompt builds on the output of the previous one.

For example, a deployment workflow might go: scaffold the project structure, implement the feature, run tests, fix any failures, then push to the repository. Each step is a separate prompt to Claude Code, with context carried forward through the conversation.

The limitation of pure sequential workflows is that they are linear. Every step waits for the previous one to finish. For tasks that do not actually depend on each other, like linting and type checking, you are wasting time.

Parallel Fan-Out Workflows

Fan-out orchestration is where you launch multiple tasks simultaneously and collect the results. This is where worktrees and subagents combine into something greater than either one alone.

Imagine you are preparing a release. You need to: update the changelog, bump the version number, generate the API docs, and run the full test suite. None of these tasks depend on each other. With fan-out orchestration, you can start all four tasks at once, each in its own subagent or worktree, and combine the results when they all finish.

To implement fan-out, define your tasks clearly: what each one should produce, what inputs it needs, and where it should write its output. Then launch all the tasks. The orchestration layer watches for completions and gathers results once every task has reported back.

Conditional Branching in Workflows

Real-world workflows often need decision points. If tests pass, deploy to staging. If tests fail, report the failures and trigger a fix loop. This branching logic adds significant power to your automation.

The implementation pattern is simple: after each task completes, check its result against your conditions. If a task outputs a success status, route to the next step in the happy path. If it outputs a failure status, route to a recovery step instead.

Practical Workflow: Feature Development End to End

Let us walk through a concrete example that ties all three patterns together. Suppose you are building a user profile feature that needs a backend API, a frontend component, tests, and documentation.

Step 1: Plan and Delegate Research

Start by defining the scope of the feature. What endpoints do you need? What does the UI look like? What are the acceptance criteria? Use Claude Code to draft a specification by delegating research tasks to subagents. One subagent reviews your existing API patterns. Another checks how similar features are documented. A third looks at frontend conventions for profile pages.

Step 2: Parallel Implementation

Once the plan is clear, create worktrees for each implementation track. In the backend worktree, have Claude Code implement the API endpoints with proper validation and error handling. In the frontend worktree, have a separate Claude Code instance build the UI component. In the testing worktree, have a third instance write test cases based on the specification you created.

Step 3: Review and Integration

When all three implementations are complete, review each independently. Check that the API contract matches what the frontend expects. Verify that tests cover the acceptance criteria. Merge each branch in order: backend first, then frontend, then tests. Resolve any conflicts that arise during the merge.

Step 4: Documentation and Deployment

Finally, orchestrate the release steps. Update the changelog, regenerate the API documentation to reflect the new endpoints, and run the full test suite against the integrated code. Each of these is a natural subagent task that runs after the merge is complete.

If you find yourself working on plugin-based tools and want to streamline common workflows, look at our guide on building Claude Code plugins with custom commands and hooks. For handling async communication patterns between agents, see our tutorial on securing MCP servers for Claude Code integration.

Avoiding Common Pitfalls

These patterns are powerful, but they come with real failure modes. Knowing what can go wrong helps you avoid the most common mistakes.

Context Drift in Long-Running Subagents

Subagents can lose track of the original task if the instructions are vague or if the context window fills up during long operations. The symptom is a subagent that returns a result that almost solves the problem but misses a key requirement.

The fix is to be specific in your subagent instructions. Include the exact deliverable format, the acceptance criteria, and any constraints the result must satisfy. If the task might exceed one context window, break it into smaller subtasks that each finish within a single agent session.

Merge Conflicts Across Worktrees

When two worktrees modify the same file and you try to merge both branches, git will report a conflict. This becomes more likely as the number of active worktrees increases and as branches diverge over time.

The best defense is to merge or rebase frequently. Pull changes from the main branch into your feature worktree every day, resolving conflicts as they appear in small increments rather than letting them accumulate until merge day. The smaller the conflict, the easier it is to resolve correctly.

Scaling Your Workflow Over Time

Start simple and add complexity only when you feel the pain. Most teams get significant value from just subagents alone, without ever touching worktrees or orchestration. Subagents are the lowest-effort, highest-impact pattern to adopt first.

Once you are comfortable spawning subagents for isolated tasks, introduce worktrees when you hit the mid-context wall. That is the moment when your main conversation gets crowded and you need to work on two things at once. Worktrees let you have two independent Claude Code sessions running without context contamination.

Orchestration comes last, and only if your team has written enough reusable workflows that someone else needs to trigger them. If you find yourself explaining the same 10-step sequence to a colleague, that is the signal to codify it as an orchestratable workflow.

If you are also working with other AI systems, our guide on building custom MCP servers for Hermes Agent shows how to extend your orchestration capabilities beyond Claude Code into a broader AI toolchain.