Claude Code Subagent Patterns: How to Break Big Tasks into Bounded Scopes

If you've ever given Claude Code a massive task — "refactor the entire auth system" — and watched it spiral into confusion after 20 minutes, you've hit the core problem: unbounded scope kills context.

The solution is subagent patterns: structured ways to decompose work into bounded, parallelizable units.

Why Big Tasks Fail in Claude Code

Claude Code has a finite context window. When you give it a large task:

• It reads lots of files → context fills up

• It loses track of what it read first

• It starts making contradictory changes

• You hit the context limit mid-task

• The session crashes and you lose progress

The fix isn't a bigger context window — it's smaller tasks.

The Subagent Pattern

Instead of one Claude session doing everything, you run multiple focused sessions:

# Don't do this:

"Refactor the entire auth system, update all tests, fix the API endpoints, and update docs"

Do this instead — 4 bounded tasks:

Session 1: Refactor auth/login.js only

Session 2: Update auth tests only

Session 3: Fix /api/auth/* endpoints only*

Session 4: Update auth docs only`

Enter fullscreen mode

Exit fullscreen mode

Each session has a clear scope, a clear input, and a clear output.

Setting Up Parallel Subagents with tmux

# Create 4 panes tmux new-session -d -s work tmux split-window -h tmux split-window -v tmux select-pane -t 0 tmux split-window -v

# Create 4 panes tmux new-session -d -s work tmux split-window -h tmux split-window -v tmux select-pane -t 0 tmux split-window -v

Launch each agent in its own branch

tmux send-keys -t work:0.0 'git checkout -b feat/auth-refactor && claude' Enter tmux send-keys -t work:0.1 'git checkout -b feat/auth-tests && claude' Enter tmux send-keys -t work:0.2 'git checkout -b feat/auth-api && claude' Enter tmux send-keys -t work:0.3 'git checkout -b feat/auth-docs && claude' Enter`

Enter fullscreen mode

Exit fullscreen mode

Now each agent works in its own git branch — no conflicts, clear ownership.

The Bounded Scope Contract

For each subagent, define:

Input: What files can this agent read? Output: What files will this agent change? Constraint: What must this agent NOT touch?

# CLAUDE.md for auth-refactor branch

Scope

• READ: auth/login.js, auth/session.js, auth/middleware.js
• WRITE: auth/login.js, auth/session.js, auth/middleware.js
• DO NOT TOUCH: tests/, api/, docs/, any file outside auth/

Task

Refactor auth to use JWT instead of sessions. Do not change function signatures — other code depends on them.`

Enter fullscreen mode

Exit fullscreen mode

This CLAUDE.md scopes the agent's work. It won't accidentally break tests or API files.

The Orchestrator Pattern

For complex workflows, use an orchestrator session to coordinate:

# orchestrator/CLAUDE.md

Your job

You are the orchestrator. You:

1. Break down the main task into subtasks
2. Write task files to tasks/task-1.md, tasks/task-2.md, etc.
3. Each task file becomes input for a subagent
4. After subagents complete, you review and merge

Do NOT implement anything yourself

Only plan, delegate, and review.`

Enter fullscreen mode

Exit fullscreen mode

The orchestrator just creates task files. Subagents read task files and implement.

Practical Example: Feature Branch Workflow

Here's a real workflow for adding a new feature:

# 1. Orchestrator breaks down the feature cd /project cat > orchestrator-task.md << 'EOF' Feature: Add user notifications

# 1. Orchestrator breaks down the feature cd /project cat > orchestrator-task.md << 'EOF' Feature: Add user notifications

Break this into 4 independent subtasks:

• Backend: Create notifications table and model
• API: Create /api/notifications endpoints
• Frontend: Create NotificationBell component
• Tests: Write tests for all of the above

For each subtask, create tasks/task-N.md with:

• Files to create/modify
• Interfaces that must match (API contracts)
• Files to NOT touch EOF

claude < orchestrator-task.md

2. Now tasks/ has 4 files. Run subagents:

for i in 1 2 3 4; do git checkout -b feat/notif-task-$i main claude < tasks/task-$i.md git add -A && git commit -m "task $i complete" done

3. Merge all branches

git checkout main for i in 1 2 3 4; do git merge feat/notif-task-$i --no-ff done`

Enter fullscreen mode

Exit fullscreen mode

Handling Conflicts Between Subagents

The most common conflict: two agents modify the same shared file.

Prevention: In each agent's CLAUDE.md, explicitly list shared files as READ-ONLY:

## Shared files — READ ONLY

• src/types.ts — read this for type definitions, do NOT modify
• src/config.js — read this for config, do NOT modify
• package.json — do NOT modify`

Enter fullscreen mode

Exit fullscreen mode

If conflicts happen anyway:

# After merging, check for conflicts git status | grep "both modified"

# After merging, check for conflicts git status | grep "both modified"

For each conflict, run a resolution agent:

cat > resolve-task.md << 'EOF' Resolve the merge conflict in src/types.ts. Branch feat/notif-task-1 added UserNotification type. Branch feat/notif-task-2 added NotificationSettings type. Both types should exist. Merge them without removing either. EOF claude < resolve-task.md`

Enter fullscreen mode

Exit fullscreen mode

Rate Limits and the ANTHROPIC_BASE_URL Fix

Running 4 parallel Claude Code sessions means 4x the token usage. You'll hit rate limits fast.

The fix is to route all sessions through a proxy that removes rate limits:

export ANTHROPIC_BASE_URL=https://simplylouie.com/api/claude

Now all 4 sessions share a single rate-limit-free connection`

Enter fullscreen mode

Exit fullscreen mode

SimplyLouie is ✌️2/month — less than the cost of one interrupted multi-agent session. Set the env var and your parallel workflows run uninterrupted.

Summary

Pattern Use when

Sequential subagents Tasks have dependencies

Parallel subagents Tasks are independent

Orchestrator Task breakdown is complex

Bounded scope CLAUDE.md Any multi-file task

The rule: one context window = one bounded scope. Break your work to fit the tool, not the other way around.

Running parallel Claude Code agents? Set ANTHROPIC_BASE_URL to avoid rate limits mid-session. SimplyLouie — ✌️2/month.