---

Part 1: The basics

What are agent teams?

Agent teams means: instead of working in one Claude chat, you have multiple specialised agents working in parallel on different parts of your project. One agent builds the frontend, one handles the API, one writes tests — and you orchestrate.

This runs through Claude Code in the terminal (not claude.ai in the browser). Claude Code is a CLI tool that lets agents work directly in your filesystem — with real file access, terminal commands, and the ability to write, run, and test code.

What you need

Essential:

• Claude Code CLI — install via npm install -g @anthropic-ai/claude-code. Needs an Anthropic API key or Claude Max/Pro subscription.
• Terminal — each agent runs in its own terminal tab or window.
• Visual Studio Code (recommended) — the best editor for working with Claude Code.
• Git — non-negotiable. Each agent should ideally work on its own branch or worktree.
• Node.js 18+ — required for Claude Code.

Nice to have:

• GitHub Copilot — pairs well with Claude Code for inline completions.
• tmux or Screen — for terminal power users managing many sessions at once.
• Docker — if agents need isolated environments.

VS Code setup

1. Open VS Code and your project directory
2. Open the integrated terminal (Ctrl+Backtick)
3. Split the terminal into multiple panels (right-click → Split Terminal)
4. Start a Claude Code agent in each panel with claude
5. Optional: use the Claude Code VS Code extension for an integrated experience

💡 Tip: name your terminal tabs after the agent role, e.g. "Agent: Frontend", "Agent: Backend", "Agent: DevOps". Keeps the overview clean.

Part 2: Good prompts for agents

Ground rules for agent prompts

Agents work best with clear limits, concrete context, and a defined role.

1. Define role + scope

You are the Frontend agent. You work exclusively in /src/components
and /src/pages. You use Next.js 14 with App Router,
Tailwind CSS, and TypeScript. You touch NO backend files.

2. Name the tech stack explicitly

Tech stack:
- Next.js 14 (App Router, Server Components where possible)
- TypeScript strict mode
- Tailwind CSS (no custom CSS files)
- Shadcn/ui for UI components
- Stripe for payments (stripe npm package)
- Resend for email

3. Hand over file conventions

File conventions:
- Components: PascalCase (e.g. CourseCard.tsx)
- Utilities: camelCase (e.g. formatPrice.ts)
- API routes: route.ts in /app/api/[endpoint]/
- Types: types.ts per feature folder

4. Spell out expected output

Build the complete component with:
- TypeScript types/interfaces
- Error handling
- Loading states
- Responsive design (mobile first)
- Accessibility (aria-labels, keyboard navigation)

Example prompts by role

Frontend agent:

You are the Frontend agent for an online coaching platform.
Your scope: all UI components and pages in /src.
Tech: Next.js 14 App Router, TypeScript, Tailwind, Shadcn/ui.
You consume APIs the Backend agent exposes.
API base URL: /api/
Auth: NextAuth.js session (useSession hook).

Backend agent:

You are the Backend agent. Your scope: /src/app/api/, /src/lib/,
database schema, and middleware.
Tech: Next.js API routes, Prisma ORM, PostgreSQL, Stripe SDK, Resend.
You build REST endpoints the Frontend agent consumes.
Document every endpoint with input/output types.

DevOps agent:

You are the DevOps agent. Your scope: deployment config,
environment variables, CI/CD, Docker.
Tech: Vercel, GitHub Actions, PostgreSQL (Supabase).
You touch no application code — only config files.

Part 3: Plan Mode — think first, build second

What is Plan Mode?

Plan Mode is a Claude Code feature that lets you have the agent produce a detailed plan first before writing any code. Especially important with agent teams because:

• All agents need to understand the same architecture
• Interfaces (APIs, types, data models) must be defined up front
• Conflicts between agent changes are avoided

How to use Plan Mode

Step 1: enable Plan Mode

Start Claude Code and switch with Shift+Tab into Plan Mode (or type /plan). The agent thinks but doesn't write code.

Step 2: give the architecture prompt

I'm building an online coaching platform with payments and a gated
course area. Produce a detailed technical plan:

1. Project structure (folders + files)
2. Data model (User, Course, Module, Chapter, Payment)
3. API endpoints (all routes with method, input, output)
4. Auth flow (registration, login, payment → access)
5. Deployment architecture

Write NO code. Plan only.

Step 3: review the plan and adjust

Step 4: save the plan as a reference document in ARCHITECTURE.md or PLAN.md.

Step 5: distribute the plan to all agents

Every agent gets as its first prompt:

Read PLAN.md in the project root. That's our architecture plan.
You are the [role] agent. Work exclusively on your part.

Why this matters so much

Without Plan Mode you get this: the Frontend agent builds a login at /api/auth/login, the Backend agent builds /api/users/authenticate. Both work hard — but nothing fits together. Plan Mode = single source of truth.

Part 4: Worked example — online coaching platform

The project

A site for a fictional course "AI Webdesign Masterclass" — an online coaching programme teaching how to use AI to build websites.

Features:

• Landing page with the course pitch
• Payment via Stripe (one-off)
• After payment: access to the gated course area
• Email confirmation after purchase (via Resend)
• 3 modules with 3 chapters each (video, text, graphics)

Agent split

For this project we use 4 agents:

Agent	Role	Scope	Terminal tab
🏗️ Architect	Plans the whole structure (Plan Mode)	PLAN.md, data model, API contracts	Tab 1
🎨 Frontend	Builds UI, pages, components	/src/components, /src/app/(public), /src/app/(course)	Tab 2
⚙️ Backend	APIs, auth, payments, email	/src/app/api, /src/lib, /prisma	Tab 3
🧪 QA/Test	Writes tests, checks integration	/tests, /e2e, linting	Tab 4

Step by step

Phase 1: Planning (Architect agent, Plan Mode)

/plan

I'm building "AI Webdesign Masterclass" — an online coaching platform.

Requirements:
- Next.js 14 App Router, TypeScript, Tailwind, Shadcn/ui
- Stripe Checkout (one-off €297)
- NextAuth.js (email + Google login)
- Prisma + PostgreSQL (Supabase)
- Resend for transactional email
- Gated course area after payment
- 3 modules × 3 chapters

Produce:
1. Full folder structure
2. Data model (Prisma schema)
3. All API endpoints with types
4. Auth + payment flow
5. Routing structure (public vs. protected)

Plan only. No code.

Result: a PLAN.md with the full architecture.

Phase 2: Parallel development

Frontend and Backend agents start at the same time, both referencing PLAN.md.

Phase 3: Integration & testing

The QA agent checks auth flow, payment flow, course area, and writes E2E tests with Playwright.

Typical problems & fixes

Problem	Fix
Agents overwrite each other	Use Git worktrees: each agent works in its own worktree
API contracts don't align	Define shared types in /src/types/ BEFORE starting the agents
Agent loses context	Have it read PLAN.md first + create a CLAUDE.md with project rules
Merge conflicts	Clear folder boundaries per agent. Agents NEVER touch the same files
Agent tries to do too much at once	Smaller, sequential tasks instead of "build everything"

Part 5: Best practices

1. Always start with Plan Mode. No agent writes code before the architecture exists.

2. CLAUDE.md is your manifest. Put a CLAUDE.md in the project root with tech stack, conventions, and rules. Every agent reads it automatically.

3. One agent = one scope. Never let two agents work in the same files.

4. Shared types first. Before frontend and backend run in parallel, the shared TypeScript interfaces must exist.

5. Small batches, frequent commits. Have each agent commit after every feature. You can roll back any time.

6. Git worktrees for pros. git worktree add ../agent-frontend feature/frontend — every agent has its own directory.

7. Build in review rounds. After every phase: stop, review code, then continue. Don't let it run blindly.

Cheatsheet

Action	Command / shortcut
Start Claude Code	claude in terminal
Enable Plan Mode	Shift+Tab or /plan
New terminal for an agent	Ctrl+Shift+5 (VS Code split)
Give agent context	"Read PLAN.md. You are the [role] agent."
Create a worktree	git worktree add ../agent-name branch-name
Stop all agents	Ctrl+C in each terminal