title: "Exercises — Sub-Agents" last_updated: 2026-03-21 status: proven difficulty: intermediate prerequisites: [03-prompting-for-agents]

Exercises — Sub-Agents

These exercises are designed to build your intuition for when and how to delegate to sub-agents. Work through them in order — each builds on skills from the previous one.

Use your own real project for all exercises. The observations you make will be specific to your codebase, which is exactly what makes them valuable.

Exercise 1: The Research Dispatch

Objective

Learn how exploration sub-agents work by dispatching one to map your project's architecture, then comparing its findings to your own understanding.

Steps

  1. Before starting, write down your own mental model of your project's architecture. Spend five minutes listing the major modules, their responsibilities, and how they connect. Keep this list private — do not share it with the agent.

  2. Start a new agent session in your project directory.

  3. Give the agent this prompt (adapt the project name):

    Use an explore agent to investigate this codebase and produce an
architecture summary. It should identify:
- The major modules or components
- The responsibility of each
- The key dependencies between them
- Any patterns or conventions it notices
- Areas that seem under-tested or under-documented

The explore agent should read broadly, not just the top-level files.
Return a structured summary.

  4. Wait for the sub-agent to complete. Read its full report.

  5. Compare the sub-agent's findings against your private list. Note:

    • What did the sub-agent find that you forgot or did not think of?
    • What did you know that the sub-agent missed?
    • Where did the sub-agent's understanding differ from yours?

  6. If using Codex CLI, run this as a standalone session with a similar prompt. The exercise works the same way — the tool handles it in a single session rather than dispatching a sub-agent, but the comparison is equally valuable.

Expected Outcome

The sub-agent should produce a reasonable architecture map. It will likely find structural patterns you take for granted and miss domain-specific knowledge that is not in the code. The delta between your understanding and the agent's tells you what context is missing from your project memory files — useful input for Module 02.

Hints

  • If the sub-agent's report is superficial, the codebase may be large enough that it needs more specific direction. Try narrowing the scope: "Focus on the src/api/ directory."
  • If you use Claude Code, watch which files the explore agent reads. This tells you how the agent navigates your codebase — useful information for writing future prompts.

Exercise 2: Fan-Out/Fan-In

Objective

Experience the fan-out/fan-in pattern firsthand by dispatching parallel sub-agents for independent tasks and observing how the parent coordinates the results.

Steps

  1. Identify three independent tasks in your project. Good candidates:

    • Add tests to three different modules
    • Add input validation to three separate endpoints
    • Write documentation for three unrelated functions
    • Fix three independent linting issues

    The key requirement: the tasks must be truly independent. No shared files, no ordering dependencies.

  2. Write a single prompt that asks the agent to use parallel sub-agents:

    I need these three tasks done in parallel. Use a separate agent for each:

1. [First task with full context]
2. [Second task with full context]
3. [Third task with full context]

Each task is independent — the agents should not need to coordinate.
After all three finish, summarize what was done.

  3. Observe the execution. Pay attention to:

    • How the parent decomposes the work
    • Whether the sub-agents truly run in parallel
    • How the parent synthesizes the results
    • How long the total process takes

  4. After completion, review each sub-agent's work individually. Check for consistency — did all three follow the same patterns, naming conventions, and code style?

  5. If using Codex CLI, run three separate sessions in parallel (three terminal windows or background processes). You act as the parent — decompose, dispatch, and synthesize yourself.

Expected Outcome

The three tasks should complete faster than they would sequentially (in Claude Code). The results should be functionally correct but may have minor inconsistencies in style or approach — this is the tradeoff of parallel independent work. The synthesis step (done by the parent or by you) is where those inconsistencies get resolved.

Hints

  • If you cannot identify three independent tasks, creating test files for three separate modules is almost always a safe choice.
  • If one sub-agent fails while the others succeed, that is fine. Note what caused the failure — it is usually an underspecified prompt. The other sub-agents' work is not affected.
  • For Codex CLI users: use git stash or branches to isolate each session's changes if they might conflict.

Exercise 3: The Handoff Quality Test

Objective

Demonstrate the impact of prompt quality on sub-agent output by running the same task with a vague prompt and a detailed prompt, then comparing results.

Steps

  1. Choose a single, moderately complex task. Good examples:

    • Add comprehensive error handling to a module
    • Refactor a function to follow a specific pattern
    • Add validation to a data processing pipeline

  2. Write two prompts for the same task.

    The vague prompt:

    Use a sub-agent to improve the error handling in src/api/orders.ts.

    The detailed prompt:

    Use a sub-agent to add error handling to src/api/orders.ts. Specifically:
- Wrap the database calls in try/catch blocks
- Use the AppError class from src/errors/AppError.ts for all thrown errors
- Log errors using the logger from src/utils/logger.ts
- Return appropriate HTTP status codes: 400 for validation errors,
  404 for not-found, 500 for unexpected errors
- Follow the pattern established in src/api/users.ts
- Add tests for each error case in src/api/__tests__/orders.test.ts
Do not modify any other files.

  3. Run the vague prompt first. Save the results (use git diff > /tmp/vague-result.diff or similar).

  4. Revert the changes (git checkout .).

  5. Run the detailed prompt. Save these results too.

  6. Compare:

    • Did both produce working code?
    • Which matched your project's conventions better?
    • Which required less follow-up correction?
    • How did token usage compare?

Expected Outcome

The detailed prompt should produce significantly better results — closer to your expectations, more consistent with existing patterns, fewer issues to fix. The vague prompt will likely produce something that technically works but diverges from your project's style or misses important requirements.

This exercise makes the abstract principle concrete: the prompt is the handoff, and handoff quality determines output quality.

Hints

  • Revert completely between runs. Use git checkout . to reset all changes. You want a clean comparison.
  • If both prompts produce identical results, your task may be too simple. Try something with more design choices.
  • Document the specific differences you observe. This becomes reference material for writing better prompts in the future.

Exercise 4: Worktree Isolation

Objective

Understand how worktree isolation prevents conflicts when parallel sub-agents modify overlapping parts of the codebase.

Steps

  1. Identify a refactoring task that touches shared code. Good candidates:

    • Renaming a commonly-imported utility function
    • Changing a shared type definition that multiple modules reference
    • Updating a logging pattern across several files that all import the same logger

  2. First, try without isolation. Ask the agent to use parallel sub-agents to make the changes across multiple modules without worktree isolation:

    Refactor the [shared pattern] across these three modules in parallel:
- src/api/users.ts
- src/api/orders.ts
- src/api/products.ts

Each may need to update the shared import in src/utils/[shared-file].ts.
Use parallel agents without worktree isolation.

  3. Observe what happens. Note any conflicts, overwrites, or inconsistencies.

  4. Revert the changes.

  5. Now try with worktree isolation:

    Refactor the [shared pattern] across these three modules in parallel.
Use worktree-isolated agents so each has its own copy of the files:
- Agent 1: src/api/users.ts
- Agent 2: src/api/orders.ts
- Agent 3: src/api/products.ts

Each may need to update the shared import in src/utils/[shared-file].ts.
Use worktree isolation to prevent conflicts.

  6. Compare the two approaches:

    • Did the non-isolated version produce conflicts?
    • How did the isolated version handle the shared file?
    • Was the merge process smooth?

  7. For Codex CLI users: simulate worktree isolation using git branches. Create a branch for each task, run a separate Codex session on each branch, then merge them. Note any merge conflicts and how you resolve them.

Expected Outcome

The non-isolated version should produce at least one conflict or overwrite in the shared file. The isolated version should handle the parallel work cleanly, with each sub-agent's changes preserved in its own worktree. The merge step may still require resolving conflicting changes to the shared file, but the conflicts will be explicit and manageable rather than silent overwrites.

Hints

  • If your codebase does not have obvious shared files, create a small test scenario: three modules that all import the same utility, and a task to update how that utility is called.
  • Worktree isolation adds overhead. The point of this exercise is to experience both approaches so you can make an informed choice about when the overhead is justified.
  • If you are on Codex CLI and git merge conflicts arise, that is the expected behavior. The exercise is about understanding why isolation matters, not about avoiding all friction.

Exercise 5: The Cost Calculator

Objective

Build intuition for the cost-benefit tradeoff of sub-agents by comparing a single-session approach against a sub-agent approach for the same task.

Steps

  1. Choose a task that is complex enough to benefit from sub-agents but feasible in a single session. Good examples:

    • Add input validation and tests to 5 API endpoints
    • Write documentation for 4 modules
    • Add logging to 6 service functions

  2. Run the task in a single session (no sub-agents):

    Add input validation to all five of these endpoints: /users, /orders,
/products, /inventory, /reports. Do them one at a time, sequentially.
Follow the pattern in src/validation/schemas.ts. Add tests for each.

    Record:

    • Total wall-clock time from start to finish
    • Total token usage (check your API dashboard or the tool's output)
    • Quality of the output (does it work? is it consistent?)

  3. Revert all changes.

  4. Run the same task with sub-agents:

    Add input validation to these five endpoints. Use parallel agents,
one per endpoint:
1. /users - [specific validation requirements]
2. /orders - [specific validation requirements]
3. /products - [specific validation requirements]
4. /inventory - [specific validation requirements]
5. /reports - [specific validation requirements]

Each agent should follow the pattern in src/validation/schemas.ts
and add tests. Run all five in parallel.

    Record the same metrics: time, tokens, quality.

  5. Compare:

    • Time. The sub-agent version should be faster in wall-clock time, possibly significantly.
    • Tokens. The sub-agent version will likely use more total tokens due to startup overhead for each sub-agent (each reads files independently).
    • Quality. Check for consistency. Did the single-session version produce more consistent code (because one agent did everything)? Did the sub-agent version have style inconsistencies across the five endpoints?

  6. Calculate the effective cost-per-minute for each approach. If the sub-agent version costs $2 in tokens but takes 5 minutes, and the single-session version costs $1.20 but takes 15 minutes, what is your time worth?

Expected Outcome

You should find that sub-agents trade tokens for time. The parallel approach finishes faster but uses more total tokens. Quality is comparable, though the single-session approach may be slightly more consistent because one agent maintained a unified mental model across all five tasks.

The "right" choice depends on your situation. If you are blocked waiting for the agent and your time is expensive, sub-agents win. If you are running tasks in the background and token cost matters more than speed, a single session is more economical.

Hints

  • Record token usage before and after each run. Most tools show cumulative token usage somewhere in their interface or API dashboard.
  • If you cannot measure tokens precisely, estimate based on session length and number of tool calls. The relative comparison is more important than absolute numbers.
  • For Codex CLI: the "sub-agent" version means running five parallel Codex sessions. The comparison is still valid — you are comparing sequential vs. parallel execution.
  • Do not obsess over the exact numbers. The goal is to build intuition, not to produce a precise cost analysis. After this exercise, you should have a gut sense for when sub-agents are worth the overhead and when they are not.