Claude Code Multi-Agent Setup for Beginners: Models, Roles, and Your First Project

A single AI coding assistant can plan a feature, write code, run tests, and review the result. However, asking one agent to perform every responsibility in the same conversation can make the workflow difficult to control.

A simple multi-agent setup gives each agent one clear role.

For a beginner project, four agents are enough:

PM Agent → Architect Agent → Developer Agent → QA Agent

The PM defines what should be built. The Architect decides how it should be structured. The Developer implements one task at a time. The QA Agent checks whether the result meets the requirements.

This setup does not require a complicated autonomous system. Claude Code remains the main coordinator and delegates focused work to each custom agent.

Version note: Claude Code commands, model names, agent frontmatter fields, and available model identifiers may change. Before using the examples, check the current /agents and /model menus and compare them with the latest official Claude Code documentation.

Recommended Model for Each Agent

A practical beginner configuration is:

Agent	Recommended model	Main responsibility
PM Agent	Sonnet	Scope, requirements, tasks, and acceptance criteria
Architect Agent	Fable 5, if available	Architecture, technical decisions, and risk analysis
Developer Agent	Sonnet	Implementation, code changes, and test execution
QA Agent	Sonnet	Requirement review, testing, and regression analysis

If your Claude Code installation does not list Fable 5, use the strongest reasoning model available, such as Opus.

A lower-cost configuration is:

PM Agent        → Sonnet
Architect Agent → Fable 5 or Opus
Developer Agent → Sonnet
QA Agent        → Haiku

Haiku can handle repetitive checks and test execution. Sonnet is usually better when QA must investigate complicated failures or review several connected files.

For the simplest first setup, use Sonnet for PM, Developer, and QA, and reserve the strongest model for the Architect.

Why the Architect Gets the Strongest Model

The Architect Agent makes decisions that can affect the entire project.

It may decide:

• which technologies to use;
• how files and modules should be organized;
• how data moves through the application;
• whether a dependency is necessary;
• how external APIs should be connected;
• where security boundaries belong;
• how the project can grow later.

A weak architectural decision can cause the Developer Agent to implement the wrong structure very efficiently.

The Architect should therefore be used for high-impact decisions rather than every small code change.

Good times to call the Architect include:

• starting a new project;
• adding a database;
• connecting an external API;
• introducing authentication;
• planning a large refactor;
• changing the data model;
• investigating a system-wide performance issue.

A button label change or small validation fix usually does not require an Architect review.

How Claude Code Custom Agents Work

Claude Code custom agents are commonly stored inside:

.claude/agents/

Each agent is defined in a Markdown file with YAML frontmatter.

A simple project structure might look like:

my-project/
├── .claude/
│   └── agents/
│       ├── pm.md
│       ├── architect.md
│       ├── developer.md
│       └── qa.md
├── PROJECT_BRIEF.md
├── README.md
└── src/

The main Claude Code session coordinates the workflow.

The four agents are not necessarily holding an independent meeting with one another. Instead, the main session delegates a focused task to one agent, collects the result, and then passes the relevant output to the next role.

This controlled flow is easier for beginners to review.

Step 1: Create the Agent Directory

Open your project in the terminal and run:

mkdir -p .claude/agents

Confirm the directory:

find .claude -maxdepth 2 -type d

You should see:

.claude
.claude/agents

Before continuing, initialize Git if the project is not already a repository:

git init
git status

Git gives you a recovery point when an agent changes more than expected.

Step 2: Create the PM Agent

Create:

.claude/agents/pm.md

Add:

---
name: pm
description: Turns product ideas into scoped requirements, small tasks, and acceptance criteria. Use this agent before architecture or implementation work.
tools: Read, Grep, Glob
model: sonnet
---

You are the PM Agent.

Your responsibilities:
- Understand the user's project goal.
- Identify the target user and main problem.
- Define the first version's scope.
- Separate required features from future ideas.
- Break work into small, testable tasks.
- Write acceptance criteria for every task.
- Identify assumptions and unanswered questions.
- Produce a task list for the Architect and Developer.

Restrictions:
- Do not modify source code.
- Do not install dependencies.
- Do not make architecture decisions without Architect review.
- Do not expand the scope without clearly identifying the expansion.

Output format:
1. Product goal
2. Target user
3. Required features
4. Excluded features
5. Task list
6. Acceptance criteria
7. Open questions

The PM Agent should produce plans, not code.

Step 3: Create the Architect Agent

Create:

.claude/agents/architect.md

Add:

---
name: architect
description: Designs the technical structure of the project, compares architecture options, and prepares implementation guidance for the Developer Agent.
tools: Read, Grep, Glob
model: opus
---

You are the Architect Agent.

Your responsibilities:
- Read the project brief and PM task plan.
- Inspect the existing repository before proposing changes.
- Compare at least two reasonable technical approaches.
- Explain trade-offs involving complexity, security, cost, and maintenance.
- Prefer the simplest architecture that satisfies the requirements.
- Define modules, file responsibilities, and data flow.
- Identify dependency, API, storage, and deployment risks.
- Produce a step-by-step technical plan for the Developer Agent.

Restrictions:
- Do not modify source code.
- Do not install dependencies.
- Do not implement features.
- Do not expand the product scope.
- Mark assumptions and unresolved decisions clearly.

Output format:
1. Current project assessment
2. Architecture options
3. Recommended approach
4. File and module plan
5. Data flow
6. Risks
7. Developer implementation sequence

In this example, model: opus is a conservative placeholder.

If your Claude Code /model menu lists Fable 5, replace opus with the exact model identifier supported by your installation. Do not guess the identifier from the display name.

Step 4: Create the Developer Agent

Create:

.claude/agents/developer.md

Add:

---
name: developer
description: Implements one approved task at a time according to the project brief and architecture plan.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
---

You are the Developer Agent.

Your responsibilities:
- Implement only the assigned task.
- Follow the approved architecture plan.
- Read existing code before editing.
- Preserve existing project conventions.
- Make the smallest change that satisfies the acceptance criteria.
- Run existing tests and relevant project checks.
- Summarize every modified file.
- Report unresolved problems instead of hiding them.

Restrictions:
- Do not add dependencies without approval.
- Do not change the architecture without Architect review.
- Do not modify unrelated files.
- Do not start another feature after completing the assigned task.
- Do not commit secrets, credentials, or private data.
- Do not claim success without test evidence.

After implementation, report:
1. Files changed
2. Behavior implemented
3. Tests or commands run
4. Results
5. Remaining risks

The Developer is the primary code-writing agent.

Because it has access to editing and terminal tools, review permission requests carefully. Do not approve unfamiliar administrative or destructive commands automatically.

Step 5: Create the QA Agent

Create:

.claude/agents/qa.md

Add:

---
name: qa
description: Reviews implementation against acceptance criteria, runs tests, checks regressions, and reports defects without modifying source code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are the QA Agent.

Your responsibilities:
- Read the original task and acceptance criteria.
- Inspect the Git diff.
- Confirm that only expected files changed.
- Run existing tests, lint checks, and documented verification commands.
- Test normal, invalid, empty, and edge-case behavior.
- Check related existing behavior for regressions.
- Look for unnecessary dependencies, exposed secrets, and unsafe input handling.
- Produce reproducible bug reports.

Restrictions:
- Do not modify source code.
- Do not install new tools or test frameworks.
- Do not fix defects directly.
- Send failed work back to the Developer Agent.
- Do not approve a task without evidence.

Output format:
1. Acceptance criteria reviewed
2. Commands run
3. Passed checks
4. Failed checks
5. Regression risks
6. Final result: PASS or FAIL

Keeping QA read-only creates a useful separation.

The QA Agent reports problems. The Developer Agent fixes them. QA then tests again.

Step 6: Confirm That Claude Code Can See the Agents

Start Claude Code from the project directory:

claude

Then open the agent management interface:

/agents

Confirm that the four agents appear.

Also check the available models:

/model

Verify:

• the PM Agent uses Sonnet;
• the Architect uses the intended high-reasoning model;
• the Developer uses Sonnet;
• the QA Agent uses Sonnet or Haiku;
• no model identifier is misspelled.

If an agent does not appear, check:

• the file location;
• YAML frontmatter syntax;
• agent name;
• model identifier;
• tool names;
• Markdown formatting.

Step 7: Start Your First Project

Use a small project with visible, testable behavior.

For example:

Build a browser-based Personal Reading List Tracker that lets one user add books, select a reading status, filter the list, remove books, and preserve the data locally.

Do not ask the Developer Agent to build everything immediately.

Begin with the PM Agent:

Use the PM Agent to turn this idea into a first-version project plan:

A browser-based Personal Reading List Tracker for one user. The user should be able to add a title, optionally add an author, choose a reading status, filter the list, remove books, and keep the list after refreshing the page.

Use plain HTML, CSS, and JavaScript. Do not include accounts, a backend, payments, or social features.

Review the PM output.

Confirm that it includes:

• a target user;
• required features;
• excluded features;
• small tasks;
• acceptance criteria.

Save the approved plan as:

PROJECT_BRIEF.md

Step 8: Ask the Architect for a Technical Plan

After approving the project brief:

Use the Architect Agent to inspect PROJECT_BRIEF.md and the current repository.

Do not modify files.

Recommend the simplest architecture for the first version. Define the file structure, application state, book data model, rendering flow, localStorage strategy, and implementation order.

Do not add a framework or third-party dependency unless it is clearly necessary.

The Architect may recommend:

index.html
styles.css
app.js
README.md
PROJECT_BRIEF.md

It should also define a data model such as:

{
  id: "book-001",
  title: "Kindred",
  author: "Octavia E. Butler",
  status: "finished",
  createdAt: "2026-07-11T10:30:00.000Z"
}

Review the architecture before giving the Developer access to implementation work.

Step 9: Give the Developer One Task

Start with page structure, not the entire application.

Use the Developer Agent to implement Task 1 from PROJECT_BRIEF.md.

Task:
Create the initial semantic HTML structure.

Allowed file:
- index.html

Do not modify:
- styles.css
- app.js
- PROJECT_BRIEF.md

Requirements:
- Add a visible page heading.
- Add a form with title, optional author, and reading status.
- Add an Add Book button.
- Add a status filter.
- Add a book-list container.
- Add an empty-state message.
- Associate every label with its form control.

Do not add JavaScript behavior yet.

After the Developer finishes, run:

git status
git diff

Do not depend only on the Developer’s summary.

Step 10: Send the Result to QA

Use the QA Agent:

Use the QA Agent to review the current uncommitted change.

Compare it with Task 1 in PROJECT_BRIEF.md.

Check:
- Only index.html changed.
- All required controls exist.
- Labels are connected to inputs.
- Status values match the brief.
- No dependency or external script was added.
- The HTML remains understandable for a beginner.

Do not modify files. Return PASS or FAIL with evidence.

When QA reports PASS, review the staged diff:

git add index.html
git diff --staged

Then commit:

git commit -m "Create reading list page structure"

The first multi-agent development cycle is complete.

The Recommended Agent Workflow

Use this sequence for every major feature:

User idea
→ PM defines the task
→ Architect plans the structure
→ Developer implements one task
→ QA reviews and tests
→ Developer fixes reported defects
→ QA retests
→ Human reviews the diff
→ Git commit

The human remains the final decision-maker.

Do not allow agents to approve and publish their own work without review.

Keep the Workflow Simple

A multi-agent setup can become more complicated than the project itself.

Avoid creating agents for:

• every programming language;
• every file;
• every small function;
• every possible review category.

Four agents are enough for a first project.

Add another specialized agent only when a repeated need appears, such as:

• security review;
• accessibility review;
• database migration;
• technical writing.

More agents do not automatically produce better software.

Clear responsibilities and strong boundaries matter more than agent count.

Common Beginner Mistakes

Letting Every Agent Edit Code

Keep PM and Architect read-only. QA should normally report defects instead of repairing them.

Asking the Developer to Build the Whole Project

Assign one task at a time.

Using the Strongest Model for Every Role

Reserve the most capable and expensive model for decisions that justify it.

Skipping Git Review

Agent summaries are not evidence. Use git status and git diff.

Allowing Architecture Changes During Implementation

Send major structural decisions back to the Architect.

Letting QA Install New Test Tools

QA should use the project’s existing checks unless a new tool is approved separately.

Conclusion

A beginner-friendly Claude Code multi-agent workflow does not need dozens of autonomous workers.

Start with four clear roles:

PM        → Sonnet
Architect → Fable 5 when available, otherwise Opus
Developer → Sonnet
QA        → Sonnet or Haiku

The PM defines the work. The Architect designs the solution. The Developer implements one focused task. The QA Agent checks the result against the original requirements.

The safest development loop is:

Plan
→ Design
→ Implement
→ Test
→ Review
→ Commit

Multi-agent development is useful when it increases clarity and control. It becomes harmful when agents expand the project, modify unrelated files, or approve their own unverified work.

Keep the project small, keep the roles separate, and use Git as the final record of what you accepted.

Frequently Asked Questions

Do the four Claude Code agents communicate directly with one another?

Not necessarily.

The main Claude Code session usually coordinates the workflow by delegating a task to one agent and passing relevant results to the next role.

Should the QA Agent fix problems directly?

For a beginner workflow, no.

QA should create a reproducible report. The Developer applies the fix, and QA tests it again. This keeps responsibilities clear.

Should I use Fable 5 for every agent?

Usually not.

Use the strongest model for complex architecture and high-impact technical decisions. Sonnet is generally a more practical default for frequent planning, implementation, and QA work.