Practical notes: Claude Code Agent Teams: A Practical Guide to Building a Team

This walkthrough rebuilds the path from raw materials to a working system for: Claude Code Agent Teams: A Practical Guide to Building a Team of AI Developers. The focus is operable steps, explicit checks, and code that you can drop into a repo without guessing intent. For the Overview stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

What are Claude Code Agent Teams?

When working through the What are Claude Code stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.

Team Lead

Backend
Frontend
Database
QA
Reviewer

Agent Teams are different from subagents

When working through the Agent Teams are different stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.

Main Agent
    ↓
Subagent
    ↓
Result

Team Lead
                 │
      ┌──────────┼──────────┐
      ↓          ↓          ↓
   Agent A ←→ Agent B ←→ Agent C
      │          │          │
      └──── Shared Tasks ───┘

Step 1: Enable Agent Teams

When working through the Step 1 Enable Agent stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node. When working through the Step 1 Enable Agent stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

cd my-project
claude

Step 2: Start with the project, not the agents

The Step 2 Start with stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.

Build complete authentication for this application.

Requirements:- PostgreSQL user model
- FastAPI authentication API
- React login and registration
- JWT authentication
- refresh tokens
- automated testsUse an Agent Team.Act as the Team Lead.
Inspect the repository, determine the workstreams,
identify dependencies and create the teammates required.

Step 3: Let the Team Lead break the project down

The Step 3 Let the stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.

Authentication Design
Database Schema
API Implementation
Frontend UI
Integration
Testing
Security Review

Step 4: Identify what can actually run in parallel

The Step 4 Identify what stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts. The Step 4 Identify what stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Schema
↓
API
↓
Integration

Backend
Frontend
Test Planning
Documentation
Security Review

Step 5: Create specialized teammates

For the Step 5 Create specialized stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness.

Team Lead
├── Backend Engineer
├── Frontend Engineer
├── Database Engineer
├── QA Engineer
└── Reviewer

Step 6: Give every agent clear ownership

For the Step 6 Give every stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness.

Help with backend.

Backend Agent owns:

/api
/services
/auth

/pages
/components
/hooks

/schema
/migrations

/tests

Step 7: Use the shared task list

For the Step 7 Use the stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness. For the Step 7 Use the stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

[ ] Database schema
[ ] Registration API
[ ] Login API
[ ] Login UI
[ ] Registration UI
[ ] Integration tests
[ ] Security review

[x] Database schema
[x] Registration API
[x] Login API
[ ] Login UI
[ ] Registration UI
[ ] Integration tests
[ ] Security review

Step 8: Let teammates communicate

When working through the Step 8 Let teammates stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.

Frontend → Backend

What does POST /auth/login return?

{
  "access_token": "...",
  "refresh_token": "...",
  "user": {
    "id": 10,
    "email": "user@example.com"
  }
}

Step 9: Keep the Team Lead focused on coordination

When working through the Step 9 Keep the stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.

Act primarily as the Team Lead.

Your responsibilities are:- understand the project
- decompose the work
- create tasks
- assign tasks
- identify dependencies
- monitor blockers
- coordinate teammates
- review completed work
- manage integration
- verify the final solutionDelegate implementation whenever appropriate.

Step 10: Let agents pick up new work

When working through the Step 10 Let agents stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node. When working through the Step 10 Let agents stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Claim Task
↓
Work
↓
Complete
↓
Check Backlog
↓
Claim Next Task

Create an initial task backlog.

Agents should claim available tasks that match their role.When a teammate finishes its current task,
it should check the shared task list and claim
the next appropriate unblocked task.

Step 11: Make dependencies explicit

The Step 11 Make dependencies stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.

API Contract
Backend
Frontend
Integration Tests

API Contract
         /        \
    Backend     Frontend
         \        /
       Integration

Identify task dependencies before work begins.

Do not allow agents to start blocked tasks.When a dependency is completed,
unblock the appropriate downstream task.

Step 12: Add an independent reviewer

The Step 12 Add an stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.

Developers
    ↓
Reviewer
    ↓
Fixes

Create a Senior Code Reviewer teammate.

Do not use this teammate for feature development initially.Its responsibility is to review completed work for:- correctness
- architecture
- security
- duplicated logic
- error handling
- maintainability
- performanceWhen problems are identified,
create follow-up tasks for the appropriate developer.

Step 13: Add independent QA

The Step 13 Add independent stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts. The Step 13 Add independent stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Developer
   ↓
Build
   ↓
QA
   ↓
Failure
   ↓
Fix
   ↓
Retest

Step 14: Do not create too many agents

For the Step 14 Do not stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness.

Team Lead
Backend
Frontend
QA
Reviewer

Step 15: Define what “done” means

For the Step 15 Define what stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness.

Implementation complete
Tests passing
Build passing
Lint passing
Type checking passing
Integration working
Reviewer findings resolved
Documentation updated

Write code

Deliver working software

Step 16: Let the Team Lead perform final integration

For the Step 16 Let the stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Put human approval on edges that spend money or change production data. Compile-time wiring does not equal business completeness. For the Step 16 Let the stage, define the inputs, the owner of the step, and the exit criteria before changing code. Operators should be able to re-run the step from a known checkpoint without guessing hidden state. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Review changes
↓
Run tests
↓
Build
↓
Check integration
↓
Find failures
↓
Delegate fixes
↓
Retest
↓
Ship

When teammates finish:

1. Inspect all changes.
2. Review the final diff.
3. Resolve inconsistencies between workstreams.
4. Run the full test suite.
5. Run linting.
6. Run type checking.
7. Verify the frontend builds.
8. Verify the backend starts.
9. Check remaining tasks.
10. Assign fixes when failures are discovered.
11. Re-run verification.
12. Only then declare the project complete.

A reusable Agent Teams prompt

When working through the A reusable Agent Teams stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Cache stable system instructions and tool schemas. Re-sending identical preamble is a common source of burn.

Use Claude Code Agent Teams for this task.

You are the Team Lead.First inspect the repository and understand the existing architecture.Then:1. Break the objective into a task graph.
2. Identify dependencies between tasks.
3. Identify which tasks can run in parallel.
4. Create only the teammates that are genuinely useful.
5. Give every teammate a specialized role.
6. Give every teammate clear ownership.
7. Avoid multiple agents modifying the same files unless necessary.
8. Use the shared task list to coordinate work.
9. Allow teammates to communicate when information is required
   from another workstream.
10. Let teammates claim appropriate unblocked work after finishing
    their current tasks.
11. Add independent QA and review tasks.
12. Create follow-up tasks when problems are discovered.
13. Continue until all required tasks are complete.
14. Run tests, builds, linting and type checks.
15. Review the final diff yourself.
16. Do not declare completion while known issues remain.Act primarily as Team Lead.Delegate implementation whenever appropriate instead of
performing all work yourself.

When Agent Teams make sense

When working through the When Agent Teams make stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Prefer small, testable units over sprawling scripts. When a step fails, the failure should point at a single responsibility rather than a tangled pipeline. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node.

Fix this validation bug.

The bigger shift

When working through the The bigger shift stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Treat this stage as a contract between inputs and validated outputs. Name the artifacts, define success checks, and refuse silent partial completion. Checkpoint after expensive steps. Resume should not re-bill the same LLM call when an operator retries a later node. When working through the The bigger shift stage, write down the contract first: required inputs, success signal, and what happens on partial failure. That checklist keeps later code changes honest. Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

AI Coding Assistant

AI Developer

AI Agents

AI Development Team

What to learn next

The What to learn next stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope. Document the happy path and the recovery path together. Retries, human gates, and dead-letter handling are part of the product, not later polish. Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.

Claude Code
↓
Subagents
↓
Agent Teams
↓
Shared Tasks
↓
Agent Communication
↓
Parallel Development
↓
QA + Reviewer Agents
↓
Autonomous Development Teams

Operational checklist

The Operational checklist stage works best when treated as a measurable surface. Capture one golden transcript, one failure case, and the rollback note before expanding scope.

Record timings and token or query cost next to functional results. Cost visibility early prevents surprise bills when the path moves from demo to shared environments.

Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.

Add a smoke test that exercises the critical path in CI with fixtures, not live paid APIs, whenever budgets allow.

Keep configuration outside application code. Environment files, secret stores, and feature flags belong in one place operators can audit without reading the whole graph.

Keep graph state flat and typed. Nested blobs hide which node wrote which field and break resume after interrupts.

Before promoting the stack, freeze versions, capture a golden transcript for the critical path, and confirm rollback steps. Shared environments need rate limits, tenancy checks, and a clear owner for secret rotation. Prefer boring reliability over clever one-off demos.

Batch note for b860522250c5: keep provider keys out of the repo, set a per-session token ceiling, and store transcripts next to the eval fixtures so later model swaps stay comparable.