PKM

Claude Code Multi-Agent Team Pattern

3 min read

Claude Code Multi-Agent Team Pattern

A prompt pattern for spawning a persistent Lead + specialist sub-agents inside Claude Code to execute multi-phase features in parallel. Lead reads the spec, spawns agents, coordinates via a shared progress file, and enforces phase gates.

Why / When to Use

When a feature has 50+ tasks across multiple layers (backend, frontend, QA) and you want agents to work in parallel without manually re-briefing each one. Effective when tasks are well-specified in a spec-kit folder.

Core Concept / Commands

Spec-kit folder structure

specs/<feature-slug>/
├── spec.md        # Acceptance criteria, data models, API contracts
├── plan.md        # Phases, task breakdown
├── tasks.md       # Granular task list with IDs (T001, T002, ...)
└── progress.md    # Shared coordination file — agents write status here

Lead agent spawn prompt template

You are the Lead of an agent team implementing <feature>.

The spec-kit is at specs/<feature-slug>/ — read spec.md, plan.md, and tasks.md now before doing anything else.

Phases 1–N are already complete (T001–TXXX). Your scope is:
- Phase N+1: TXXX–TXXX — <Phase Name> (N tasks)
- Phase N+2: ...

---

Spawn three permanent teammates now:

**backend-agent**
- All backend tasks: models, schemas, services, endpoints, migrations, tests
- TDD strictly enforced: write the test first, then implement
- After each endpoint is ready, post the API contract to specs/<slug>/progress.md
- Working dir: backend/

**frontend-agent**
- All frontend tasks: pages, components, hooks, types, styling
- Do NOT start a task until backend-agent has posted the API contract in progress.md
- Working dir: frontend/

**qa-agent**
- Runs acceptance checks at the end of each phase before Lead advances
- Post PASS or FAIL with evidence to progress.md
- On FAIL: describe exactly what broke and which task needs revisiting

---

Coordination rules:
1. progress.md is the single source of truth
2. Mark [P] tasks as parallel-safe — assign concurrently
3. API-First: backend posts contract → frontend begins. Never reversed.
4. Phase gate: all tasks done + qa-agent posts PASS → git commit → next phase
5. Commit message format: "phase N complete: <phase name>"

---

Execute Phase N+1 first. Brief the team, assign tasks, enforce the gate, commit, then move forward. Do not wait for user input between phases unless qa-agent posts FAIL.

Start now by saying "Lead active" then read the spec-kit and create progress.md.

Before running

  1. Ensure progress.md reflects already-completed tasks — otherwise Lead may redo them.
  2. Add Vuexy/template path to CLAUDE.md if frontend agent needs it.

Key Options / Variants

Minimal 2-agent setup (solo project)

Skip qa-agent and have a single agent handle both backend and frontend sequentially when the team overhead isn’t worth it.

Phase gate enforcement

<!-- progress.md entry format -->
### Phase 4 Gate
- Tasks: T068–T088 ✅ all complete
- qa-agent: PASS — all endpoints return correct schema, tests green
- Committed: "phase 4 complete: roles and permissions"

Gotchas

  • Lead agent must read the spec-kit first before any work — otherwise it hallucinates task scope.
  • progress.md is the only shared memory — keep entries dated and structured or agents lose coordination.
  • Never reverse the API-First rule: frontend working on guessed contracts causes cascading rework.
  • Ensure completed tasks are marked in progress.md before spawning new Lead to continue — prevents re-doing finished work.

Source

Conversation “Creating an agent team prompt” — 2026-05-15, Claude Code project

Graph View