batching-patterns

What this skill does

# Batching Patterns

**Version:** 1.0.0
**Purpose:** The Golden Rule of Claude Code execution -- batch operations for maximum parallelism
**Status:** Production Ready

## Overview

The Golden Rule of Claude Code performance:

**"1 MESSAGE = ALL RELATED OPERATIONS"**

Every tool call within a single message executes in parallel (when no dependencies exist). Every separate message introduces a sequential round-trip. This distinction is the difference between a 2-minute workflow and a 10-minute one.

```
Sequential (5 separate messages):
  Message 1: Task(agent-1)  →  2 min
  Message 2: Task(agent-2)  →  2 min (waits for agent-1!)
  Message 3-5: ...           →  2 min each
  Total: ~10 minutes (serial)

Batched (1 message):
  Message 1: Task(agent-1) + Task(agent-2) + ... + Task(agent-5)
  Total: ~2 minutes (parallel, limited by slowest agent)
  Speedup: 5x
```

Each message carries API round-trip overhead. Batching eliminates N-1 round-trips.

---

## The Batching Principle

Claude Code has a simple execution model:

1. **Within ONE message:** Same tool type calls execute in parallel (no data dependencies)
2. **Across SEPARATE messages:** Tool calls execute sequentially
3. **Mixed tool types in ONE message:** May force sequential execution

```
Same tool type in one message = PARALLEL
  Task(A) + Task(B) + Task(C)  →  All run simultaneously

Different tool types in one message = SEQUENTIAL (often)
  TaskCreate(...) + Task(A) + Bash(...)  →  May run one at a time

Separate messages = ALWAYS SEQUENTIAL
  Message 1: Task(A)  →  completes first
  Message 2: Task(B)  →  starts only after A finishes
```

**Why Same Tool Type Signals Independence:**

Multiple calls of the same tool type (all Task, all Read, all Grep) signal independent operations that can run concurrently. Mixing tool types breaks this signal because different types often have implicit ordering requirements.

---

## Batching Patterns by Tool Type

### Task Tool Batching

The most impactful tool to batch -- each agent runs for minutes.

```
❌ Sequential (3 separate messages):
  Message 1: Task(security-reviewer)   → 3 min
  Message 2: Task(perf-reviewer)       → 2 min (waits!)
  Message 3: Task(a11y-reviewer)       → 2 min (waits!)
  Total: ~7 minutes

✅ Batched (1 message):
  Task(security-reviewer) + Task(perf-reviewer) + Task(a11y-reviewer)
  Total: ~3 minutes (3 agents parallel)
  Speedup: 2.3x
```

Agents are independent when they: read same input but don't modify it, write to different output files, perform different analysis, don't need each other's results.

### File Operations Batching

```
❌ Sequential Reads:
  Message 1: Read("src/auth.ts")        → round-trip
  Message 2: Read("src/middleware.ts")   → round-trip
  Message 3: Read("src/routes.ts")      → round-trip
  Total: 3 round-trips

✅ Batched Reads:
  Read("src/auth.ts") + Read("src/middleware.ts") + Read("src/routes.ts")
  Total: 1 round-trip (3x faster)
```

```
❌ Sequential Searches:
  Message 1: Grep("TODO", path="src/")
  Message 2: Grep("FIXME", path="src/")
  Message 3: Glob("**/*.test.ts")

✅ Batched Searches:
  Grep("TODO") + Grep("FIXME") + Glob("**/*.test.ts")
  All parallel in 1 round-trip
```

```
⚠️ Write/Edit Caution:
  ❌ Edit("src/auth.ts", change_1) + Edit("src/auth.ts", change_2)  ← Conflict!
  ✅ Edit("src/auth.ts", change_1) + Edit("src/routes.ts", change_2)  ← Safe
  Rule: Different files = safe to batch. Same file = must be sequential.
```

### Tasks Batching

```
❌ Individual Calls (5 round-trips):
  TaskCreate({ id: "1", title: "Step 1", status: "pending" })
  TaskCreate({ id: "2", title: "Step 2", status: "pending" })
  ...

✅ Single Call (1 round-trip):
  TaskCreate({ id: "1", title: "Step 1", status: "pending" })
  TaskCreate({ id: "2", title: "Step 2", status: "pending" })
  TaskCreate({ id: "3", title: "Step 3", status: "pending" })
  # All in same message = parallel execution
```

### Bash Batching

```
❌ Sequential Independent Commands:
  Message 1: Bash("npm run lint")
  Message 2: Bash("npm run typecheck")
  Message 3: Bash("npm run test")

✅ Parallel Independent Commands (1 message):
  Bash("npm run lint") + Bash("npm run typecheck") + Bash("npm run test")

✅ Dependent Commands Chained (1 Bash call):
  Bash("mkdir -p ai-docs && cp template.md ai-docs/plan.md")
```

---

## The 4-Message Pattern (Reference)

The canonical batching template from multi-agent-coordination:

```
Message 1: Preparation (Bash/Write only)
  - Create directories, write context files, validate inputs
  - NO Task calls, NO Tasks

Message 2: Parallel Execution (Task only)
  - ALL agents in SINGLE message, ONLY Task calls
  - Same tool type = true parallel execution

Message 3: Consolidation (Task only)
  - Consolidation agent reads all output files

Message 4: Present Results
  - Show user final consolidated results
```

**Why 4 messages:** Each depends on the previous (agents need context, consolidation needs agent outputs, presentation needs consolidated result). This is the minimum sequential steps.

---

## Anti-Patterns (Critical)

### Anti-Pattern 1: Sequential Task Launches

```
❌ Message 1: Task(agent-1)     // 2 min
❌ Message 2: Task(agent-2)     // 2 min (waits for agent-1!)
❌ Message 3: Task(agent-3)     // 2 min (waits for agent-2!)
   Total: 6 minutes

✅ Message 1: Task(agent-1) + Task(agent-2) + Task(agent-3)  // All parallel!
   Total: 2 minutes (3x speedup)
```

### Anti-Pattern 2: Mixing Tool Types in Execution Message

```
❌ Mixed Tools (sequential):
  TaskCreate({...})             // Tool type A
  Task(security-reviewer)       // Tool type B
  Bash("echo 'starting'")      // Tool type C
  Task(perf-reviewer)           // Tool type B

✅ Separated (parallel execution):
  Message 1: TaskCreate({...}) + Bash("echo 'starting'")   // Preparation
  Message 2: Task(security-reviewer) + Task(perf-reviewer) // Execution (parallel)
```

### Anti-Pattern 3: Individual Tasks Calls

```
❌ 5 separate TaskCreate calls across messages = 5 round-trips
✅ 5 TaskCreate calls in 1 message = 1 round-trip (parallel)
```

### Anti-Pattern 4: Sequential File Reads

```
❌ 5 separate Read messages = 5 round-trips
✅ 5 Read calls in 1 message = 1 round-trip (5x faster)
```

### Anti-Pattern 5: Unnecessary Dependencies

```
❌ False Dependencies:
  Message 1: Grep("authentication")  // Wait...
  Message 2: Grep("authorization")   // Wait...
  Message 3: Glob("**/*.middleware.ts")  // Wait...

✅ Recognize Independence:
  Message 1: Grep("authentication") + Grep("authorization") + Glob("**/*.middleware.ts")
```

**Dependency Detection Checklist:**

Before splitting across messages, ask:
1. Does B need the OUTPUT of A? If no, batch.
2. Do both write to the SAME file? If no, batch.
3. Does the ORDER matter? If no, batch.
4. Is B CONDITIONAL on A's result? If no, batch.

If all four are "no," operations are independent -- batch them.

---

## When NOT to Batch

- **Data dependencies:** Developer needs architect's plan before implementing
- **Same-file modifications:** Two edits to the same file must be sequential
- **Sequential phases:** Plan -> Implement -> Test -> Review (each depends on previous)
- **Order-dependent operations:** `npm install && npm build && npm test`
- **Conditional execution:** Next action depends on previous result (test pass/fail)

```
CORRECT - Sequential:
  Message 1: Task(architect)   → writes plan.md
  Message 2: Task(developer)   → reads plan.md (depends on Message 1)

CORRECT - Chained:
  Bash("npm install && npm run build && npm run test")
```

---

## Performance Impact

```
Scenario: 5-Agent Code Review
  Sequential: 10 min + 5 round-trips  |  Batched: 3 min + 1 round-trip  |  3.3x

Scenario: 7 Codebase Searches
  Sequential: ~21 seconds             |  Batched: ~3 seconds              |  7x

Scenario: 10 File Reads
  Sequential: ~20 seconds             |  Batched: ~2 seconds              |  10x
```

**Speedup Formula:**

```
Sequential = N * (execution + round_trip)
Batched    = max(executions) + round_t