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:

1. It reads lots of files → context fills up
2. It loses track of what it read first
3. It starts making contradictory changes
4. You hit the context limit mid-task
5. 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

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

# 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

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.

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.

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

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

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

If conflicts happen anyway:

# 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

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

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.