Video 23.1: Task Decomposition Strategies

Course: Claude Code - Parallel Agent Development (Course 4) Section: 23: Orchestration and Best Practices Video Length: 4–5 minutes Presenter: Daniel Treasure

Opening Hook

When you move from single-agent to parallel development, everything changes. The biggest mistake teams make is splitting work by type—one agent writes features, another writes tests. The result? Constant coordination overhead and idle waiting. Today, we're learning how to decompose work the right way: context-centric division that lets agents run truly in parallel without stepping on each other's toes.

Key Talking Points

What to say:

The Context-Centric vs. Type-Centric Trap - Type-centric division (bad): one agent builds features, another writes tests, another documents. Agents constantly need context from each other. - Context-centric division (good): each agent owns a feature AND its tests AND its docs. Everything that agent needs is already in their context window. - The cost of coordination is the cost of repeated context.

The Team Meeting Heuristic - Imagine you have a 30-minute team meeting about this task. How many people would need to be in that meeting? That's roughly how independent the subtask is. - If everyone needs to be there, the task isn't decomposed. It's artificially split work with a coordination tax. - If you could brief 2–3 people independently, you've found a good decomposition.

Task Sizing: Self-Contained Units - A well-sized task produces a clear deliverable (a feature, a module, a test suite, documentation for a feature). - Too small: coordination overhead exceeds the value of parallelization. (Assigning 100 one-line tasks to 10 agents wastes time on hand-offs.) - Too large: agents work too long without sync. Risk of duplicated effort or diverging implementations. - Sweet spot: tasks that take 30 minutes to 2 hours for a competent agent to complete.

Express Parallelization Explicitly - Don't say "parallelize this." Say "use 5 parallel tasks: (1) auth module, (2) database layer, (3) API endpoints, (4) UI components, (5) tests." - The clearer you are about what's parallel and what's sequential, the better the agents' planning. - Dependencies matter: some tasks must finish before others start. Map them.

What to show on screen:

Open a project structure (a real codebase or example)
Show a typical monolithic project: one agent, one big context window.
Walk through the file tree: auth/, database/, api/, ui/, tests/.
Decomposition diagram (whiteboard or simple text diagram)
Show BAD example: Agent A (features) → Agent B (tests) → Agent C (docs). Arrows show dependencies.
Explain the coordination tax: Agent B can't work until Agent A finishes; Agent C can't work until both are done.
Show GOOD example: Agent A (auth feature + its tests), Agent B (database layer + its tests), Agent C (API + its tests). Parallel arrows.
Dependency graph
What must finish before what can start?
Example: "database tests must pass before API agent writes endpoints. But auth and database agents can work in parallel."
Use a simple text-based DAG or draw it as boxes and arrows.
Task sizing visualization
Show an example task description that's too small: "Add one unit test." → Too much overhead.
Show one that's too large: "Build the entire backend." → Too long without sync.
Show the sweet spot: "Implement user authentication module: login endpoint, unit tests, integration tests with database. Deliverable: /src/auth module passes all tests."

Demo Plan

Scenario: You're building a Python FastAPI application with authentication, database persistence, and a React frontend. You want to parallelize the work across 4 agents.

Timing: ~3 minutes

Step 1: Analyze the Project (30 seconds)

Show the project structure: my-app/ ├── backend/ │ ├── src/ │ │ ├── auth.py │ │ ├── database.py │ │ ├── api.py │ │ ├── models.py │ │ └── tests/ │ └── requirements.txt ├── frontend/ │ ├── src/ │ │ ├── components/ │ │ ├── pages/ │ │ └── tests/ │ └── package.json └── README.md
Ask: "How would you split this work?"

Step 2: Show the Bad Decomposition (45 seconds)

Outline the type-centric approach on screen: ``` MISTAKE: Type-centric division
Agent A: Implement auth.py, database.py, api.py
Agent B: Write tests for everything Agent A wrote
Agent C: Build React frontend
Agent D: Write frontend tests

PROBLEM: Agent B is idle while Agent A works. Agent D is idle while Agent C works. ``` - Highlight the waiting periods with red boxes or comments.

Step 3: Show the Good Decomposition (45 seconds)

Outline the context-centric approach: ``` GOOD: Context-centric division
Agent A: Auth module (src/auth.py + unit tests) Deliverable: /src/auth with tests passing
Agent B: Database layer (src/database.py + integration tests) Deliverable: /src/database with tests passing
Agent C: API endpoints (src/api.py + endpoint tests) Deliverable: /src/api with tests passing NOTE: Depends on Agent A & B finishing first
Agent D: React frontend + component tests Deliverable: /frontend with tests passing Can start in parallel with A & B ```
Show the dependency arrows: A, B, D can start immediately; C waits for A and B.

Step 4: Write Out Clear Task Instructions (45 seconds)

Show what you'd actually give to each agent. Example for Agent A: ``` Task: Implement User Authentication Module

Deliverable: - src/auth.py: login(username, password), logout(), verify_token() - tests/test_auth.py: full unit test coverage (>80%) - All tests pass locally

Constraints: - Use JWT tokens, expire after 1 hour - Password hashing with bcrypt - Do NOT depend on database module (you'll use mocks)

Dependencies: None

Acceptance criteria: - pytest passes 100% of tests - Code follows PEP 8 ``` - Show the clarity: Agent A knows exactly what success looks like.

Step 5: Map Remaining Dependencies (45 seconds)

Show Agent C (API) task: ``` Task: Implement FastAPI Endpoints

Deliverable: - src/api.py: GET /users, POST /users, DELETE /users/{id} - tests/test_api.py: full endpoint tests - All tests pass

Dependencies: Agent A (auth module) and Agent B (database) Wait for: Both auth and database modules to be merged

Acceptance criteria: - pytest passes 100% of tests - All endpoints require valid JWT token - All endpoints interact with database ```

Code Examples & Commands

Example 1: Task Decomposition Script (Bash)

#!/bin/bash
# decompose.sh - Print a structured task list for parallel agents

cat << 'EOF'
PROJECT DECOMPOSITION: My Python FastAPI App
Total estimated effort: 6 agent-hours
Recommended parallelization: 4 agents

TASK 1: Authentication Module (1.5 hours)
- Scope: /backend/src/auth.py + tests
- Deliverable: login, logout, verify_token functions
- Dependencies: None
- Blocks: Task 3 (API endpoints)

TASK 2: Database Layer (1.5 hours)
- Scope: /backend/src/database.py + tests
- Deliverable: User and Post models, CRUD operations
- Dependencies: None
- Blocks: Task 3 (API endpoints)

TASK 3: API Endpoints (2 hours)
- Scope: /backend/src/api.py + tests
- Deliverable: GET/POST/DELETE endpoints
- Dependencies: Task 1, Task 2 (both must be done first)
- Blocks: Task 4 (frontend integration)

TASK 4: React Frontend (1.5 hours)
- Scope: /frontend/src/ + component tests
- Deliverable: Login form, user list, CRUD UI
- Dependencies: Task 3 (API endpoints must exist)
- Blocks: None

EXECUTION PLAN:
Start at time 0: Task 1 (auth), Task 2 (database), Task 4 (frontend skeleton)
Start at time 1.5h: Task 3 (API) -- after Task 1 & 2 complete
Start at time 3.5h: Task 4 (frontend integration) -- after Task 3 complete

Total wall-clock time: ~3.5 hours (vs 6 hours sequential)
EOF

Example 2: Dependency Graph (Python)

import json

tasks = {
    "auth_module": {
        "description": "User authentication (login, logout, verify token)",
        "depends_on": [],
        "estimated_hours": 1.5,
        "assignee": "Agent_1"
    },
    "database_layer": {
        "description": "User and Post models, CRUD operations",
        "depends_on": [],
        "estimated_hours": 1.5,
        "assignee": "Agent_2"
    },
    "api_endpoints": {
        "description": "FastAPI endpoints for users and posts",
        "depends_on": ["auth_module", "database_layer"],
        "estimated_hours": 2.0,
        "assignee": "Agent_3"
    },
    "frontend": {
        "description": "React UI components and tests",
        "depends_on": ["api_endpoints"],
        "estimated_hours": 1.5,
        "assignee": "Agent_4"
    }
}

# Print dependency graph
print("\n=== TASK DEPENDENCY GRAPH ===\n")
for task_name, task_info in tasks.items():
    deps = ", ".join(task_info["depends_on"]) if task_info["depends_on"] else "None"
    print(f"{task_name}")
    print(f"  └─ Depends on: {deps}")
    print(f"  └─ Est. time: {task_info['estimated_hours']}h")
    print(f"  └─ Assignee: {task_info['assignee']}\n")

# Calculate critical path
def calculate_critical_path(tasks):
    # Simple approach: find tasks with no dependencies (can start immediately)
    # Then trace which ones are on the longest chain
    print("\n=== CRITICAL PATH ===")
    print("Tasks that can start immediately:")
    for task_name, task_info in tasks.items():
        if not task_info["depends_on"]:
            print(f"  - {task_name} (start time: 0h)")

calculate_critical_path(tasks)

Example 3: Clear Task Description Template

# TASK: Implement Authentication Module

## Deliverable
- [ ] `/src/auth.py`: login(), logout(), verify_token() functions
- [ ] `/tests/test_auth.py`: Unit tests with >80% coverage
- [ ] All tests passing locally
- [ ] Code follows project style guide

## Description
You are building the user authentication system for our API. This module will be used by other agents building the API layer, so make it reliable and well-documented.

## Requirements
- Use JWT tokens (expire after 1 hour)
- Password hashing with bcrypt
- Return user ID on successful login
- Raise ValueError on invalid credentials
- Do NOT depend on database module yet (use mocks in tests)

## Acceptance Criteria
- `pytest tests/test_auth.py -v` passes 100% of tests
- Code follows PEP 8 (check with `black --check src/auth.py`)
- Minimum 80% test coverage
- All edge cases covered (invalid password, expired token, etc.)

## Dependencies
- None. You can work independently.

## Blocks
- Task: "Implement API Endpoints" (depends on this being done first)

## Time Estimate
1.5 hours

## Notes
- Team is using FastAPI and PyJWT
- See /docs/architecture.md for token format spec

Gotchas & Tips

Gotcha 1: Hidden Dependencies - You think Task A and B are independent, but Agent A needs a utility function from Agent B. - Tip: During decomposition, list all imports and external dependencies. If Task A imports from Task B, they're not independent.

Gotcha 2: False Parallelization - Splitting a task into 10 micro-tasks and assigning to 10 agents introduces so much coordination overhead that you lose the benefit. - Tip: Aim for 3–8 parallel tasks, not 20+. More tasks = more context switches and integration work.

Gotcha 3: Context Window Imbalance - Agent A gets a task that needs 30KB of context (large existing codebase), Agent B gets a task needing 2KB. Both run out of tokens at different rates. - Tip: During decomposition, estimate the context size each task will need. Balance it.

Gotcha 4: Merging Conflicts - If two agents both modify the same file (even different functions), you'll have merge conflicts. - Tip: Make sure each task clearly owns specific files/modules. No overlap.

Gotcha 5: Under-Specified Tasks - Vague task descriptions like "build the backend" lead to agents reimplementing each other's work. - Tip: Always include clear acceptance criteria and deliverables. The agent should know exactly when they're done.

Lead-out

Now you know how to carve up a big project into parallel work. But splitting work is only half the battle. In the next video, we're adding quality gates using hooks—ensuring agents don't move forward until their code actually works. You'll see how TeammateIdle and TaskCompleted hooks enforce standards across your whole team.

Reference URLs

FastAPI Documentation: https://fastapi.tiangolo.com/
JWT.io: https://jwt.io/
Bcrypt Documentation: https://github.com/pyca/bcrypt
Dependency Graphs (graph theory): https://en.wikipedia.org/wiki/Dependency_graph
Python Task Decomposition Best Practices: https://realpython.com/async-io-python/

Prep Reading

Anthropic Claude Code Agent SDK docs: Review the task assignment API.
"The Mythical Man-Month" by Fred Brooks: Chapter on "The Surgical Team" - classic on task decomposition.
Parallelism vs. Concurrency: Understand the difference (context-centric division assumes true parallelism).
Dependency injection patterns: Familiarize yourself with how to structure code so tasks truly are independent.

Notes for Daniel

This video is the foundation for everything that comes after in the orchestration section. Spend time on the "bad vs. good" comparison—make it visceral by showing the waiting/idle problem. The team meeting heuristic is a powerful mental model; drive it home with a relatable example (maybe reference a meeting from a fictional team or your own experience).

The demo should feel like a real project you're taking on. Use a codebase that viewers recognize (FastAPI + React is a good modern choice). Show the decomposition process step-by-step so viewers see your thinking.

Emphasize that this isn't about being perfect—it's about being explicit. Vague task splitting causes coordination chaos. Clear decomposition enables real parallelization.

Quick Reference