Same Claude, Different Roles — Splitting Into a 5-Agent Team Changed My Code Quality

April 2026 · Lazy Developer EP.19

I pushed a PR. The Claude I'd spun up as Reviewer flagged 3 edge cases and 1 memory leak. In the previous session, the Claude I'd spun up as Coder had called the same code "complete." Same Claude 4.6. Only the role was different.

That gap is why I built an agent team from scratch. Writing and validating solo meant obvious issues slipped through. A session set up as Reviewer doesn't hand out "looks fine" easily. Tell it to nitpick and it nitpicks. After confirming that, I decided to split the whole development flow by role.

EP.17 laid down harness engineering (Rules, Commands, Hooks). Sitting on top of it now is a 5-person team — Planner, Coder, Reviewer, Tester, Debugger. Claude Code subagents isolate context by design, so they don't share cumulative state across sessions. My routine needed that sharing, so I layered MCP servers for Agent-to-Agent communication and Supabase for task state on top. This post is the build log, written so you can follow along from folder layout to actual turn order.

Same Claude, Different Role — Why Quality Shifts

The principle is simple. Claude answers in line with the role you give it. Tell it "you're the developer who wrote this code," and it answers defensively. Switch to "you're a reviewer, your job is to find mistakes," and it goes straight for edge cases. Same model, different output distribution.

The problem was writing and validating in the same session. Ask Claude "did this go well?" and it tends to protect what it just wrote. Humans do the same. Reviewing your own code has blind spots. That's why I split the reviewer out.

Role separation doesn't end with one line of system prompt. Each role reads different Skills, has different tool permissions, and produces different output formats. The role isn't just "who" — it includes "what input triggers what format." The rest of this post is that "it includes" broken down, file by file.

Prerequisites (Follow-Along Checklist)

Four things you need before following along. If something's missing, set it up first.

IDE doesn't matter. VS Code, Cursor, plain terminal — any of them work. I run Claude Code CLI inside Cursor. The team runs via shell scripts, so being comfortable with tmux helps.

Assuming you're set up, the next sections build real files. Order: folder layout → system prompts → Skills → MCP servers → DB → run script. Set it up once, clone it to every project.

Folder Layout — Global vs Project

Same principle as EP.17. Put anything project-agnostic in the global area; put project-specific things inside the project. Agent definitions, system prompts, and shared Skills go global. Project rules and work state stay in-project.

The key point: the global area is built once and reused across projects. Starting a new project means writing a CLAUDE.md at the project root — the team attaches automatically. No per-project setup beyond that.

5 System Prompts (Copy-Paste Ready)

Each Agent is a single markdown file. Filename becomes the Agent name. Follow the official Claude Code subagent format: YAML frontmatter with name, description, tools, model, and the system prompt in the body. The /agents slash command gives you an interactive setup too.

Below are the prompts I actually use, trimmed for clarity. Copy them and tweak for your stack.

~/.claude/agents/planner.md

~/.claude/agents/coder.md

~/.claude/agents/reviewer.md

~/.claude/agents/tester.md

~/.claude/agents/debugger.md

These five files share a pattern: "what you do NOT do" is stated explicitly. Reviewer — no edits. Debugger — no edits. Coder — no commits. Keeping each role inside its lane is half of the quality story.

Skill Files — The Recipes Each Role Carries

The system prompt defines "who you are." The Skill defines "how you do it." Every session reads its Skills on start and follows them. Here's a condensed version of code-review.md, used by the Reviewer.

Skills include checklists, examples, and output formats. Prose explanations are minimized. When Claude references them at runtime, density beats readability. Same rule I wrote in EP.17.

I've built plan-and-spec.md, implement.md, write-tests.md, and trace-error.md in the same shape. Each Skill is bound to an Agent's system prompt with "read this Skill before starting."

MCP Servers — Permission Per Role

Five agents working on the same project share tools but need different permission levels. Wrapping them in MCP servers is the right fit. When an Agent hits an MCP endpoint, the server checks the role and serves only the allowed operations.

Here's the core of the supabase wrapper. Reads the role header and filters queries accordingly.

This one server centralizes DB permissions for all five Agents. No need to repeat prohibition rules in every system prompt — the server rejects anything outside role permissions. Agent prompts stay readable; security lives on the server side.

Same pattern for docs-search (restrict to project markdown files) and logs (restrict to last 24 hours). Putting boundaries on the server — not in the Agent — also makes debugging easier. If something goes wrong, check the MCP server log.

Supabase agent_state — Schema and Migration

The moment I split roles, I hit a wall. Coder sessions didn't know about the spec Planner had written. Different sessions don't share memory. So I created an agent_state table in Supabase and write task state there. Each Agent writes only to its own slot.

Columns are split so it's obvious which stage broke. If a session dies mid-turn, "status=reviewing, review_findings is null" immediately tells me the Reviewer turn died. Restart = run that turn again.

State-transition guards live in a Supabase Edge Function. Moving from "planning" to "coding" requires that the spec column is populated — the DB enforces it. Protects against Agents skipping steps.

There's a file trail too. docs/tasks/{task_id}.md holds human-readable output per Agent. DB is the state record, files are the reading record. When I look at output and ask "what happened?" — I open the file.

The Actual Routine — Turn Order and Script

Turns are driven by one shell script. Claude Code auto-loads subagent files at ~/.claude/agents/<name>.md. The script just tells the main session "read the current state for this task_id and delegate to that subagent." --mcp-config pins MCP servers, --append-system-prompt injects the task context.

Claude Code subagents isolate context by design. Calling a subagent from the main session starts it with a clean context, its own system prompt, and only its allowed tools. Results come back as a summary — cross-session memory isn't shared. That's exactly why I introduced the Supabase agent_state table: subagents needed "accumulated state" to pass between each other, and that has to live outside any single session.

A human gates between Agents. I don't auto-launch the next Agent. I read the output, decide to move on, and kick off the next turn. I tried full auto once and it wandered off course — manual gating is the current setup.

Here's the turn trace for a single feature.

Key point: turns are closed. A single Agent session does only its job, leaves output in files/DB, and exits. The next Agent doesn't inherit the previous session — it reads artifacts. Sessions can die without affecting restart, and re-running a middle stage is easy.

Commits stay with me. No Agent has commit permissions — the point where code enters my repo is where I want the human in the loop. Team of five, final gate is still me.

What Changed, What Didn't (Honestly)

What changed: edge cases get caught earlier. Reviewer is built to nitpick, so "looks good" doesn't come cheap. Same code Coder called fine, Reviewer finds three problems in. Coder reflects them, Reviewer re-runs, quality climbs another notch.

Debugging sped up. Debugger is a separate session, so the context is clean. It focuses on the failure log without any "I just wrote this, it should be fine" bias from Coder. Swapping sessions killed that bias.

What didn't change: final review is still mine. Five Agents pass the code, I still skim the diff. Tester sometimes writes meaningless tests. Reviewer sometimes demands a bar nothing can pass. Debugger sometimes names the wrong cause. Team or not, the last gate is a human.

Cost went up too. About 2–3x the tokens of a single-session run. Each role loads its own system prompt, and the same code gets read by multiple sessions. On the other hand, rework rounds dropped, so total wall-clock time actually went down. A token-for-time trade.

Built on the EP.17 Harness

EP.17 wired up harness engineering: Rules (CLAUDE.md), Commands (/plan-and-spec, /tdd, /verify, ...), Hooks (block-dangerous.sh). The scaffold a single Claude session works inside.

EP.19 stacks an Agent team on that harness. Same materials. The plan-and-spec command became Planner's Skill. The tdd command became Tester's Skill. Each Agent runs Commands on its turn. Hooks remain a global safety net across all Agents.

Put another way: EP.17 was a single-session workflow. EP.19 is the same workflow split into five. Starting with the split from day one would've been complicated — building the harness first, then placing a team on top, was the right sequence. Gathering materials first and assigning roles afterward is simpler.

FAQ

Q. Can the same model produce different results just by changing the role?

Yes. When the system prompt and referenced skill differ, the output distribution shifts noticeably. A session set up as Reviewer doesn't hand out "looks fine" easily. Ask it to nitpick and it nitpicks. Role setup changes the output.

Q. Aren't Claude Code subagents enough on their own?

For simple cases, yes. I needed cross-session state sharing, so I went custom. Work state persists in Supabase, and Agent-to-Agent communication runs through MCP servers. Subagents are designed to isolate context — they don't carry cumulative state across sessions by design.

Q. Is 5 the right size?

For my workflow, yes. Planner, Coder, Reviewer, Tester, Debugger. I tried splitting further, but roles started overlapping. With only 4, there was a gap — no dedicated debugger.

Q. Why MCP + an external DB?

Multiple agents had to pass the same task forward. The spec Planner wrote had to reach Coder; the code Coder wrote had to reach Reviewer. Sessions don't share memory, so I store task state in Supabase and let each Agent read its slot on its turn.

Q. How does this differ from EP.17 harness engineering?

EP.17 wired up Rules, Commands, and Hooks for a single Claude session. EP.19 stacks multiple Agents on top of that harness so each session carries one role. Same materials — what one session used to do is now split across five.

Closing

Role separation is less prompt engineering than workflow engineering. Same model, same codebase — split the session, and the result shifts. Ask the Coder to review, it shields its own work. Split off a Reviewer session, and it nitpicks. That gap is why I built the team.

80% first, then fix the remaining 20% as real problems show up. This team grew that way. Planner and Coder first. Adding Reviewer showed clearly how quality changed. Test automation was thin, so Tester joined. Debugger got split out last to kill debugging bias. Teams should grow by need.

Final review is still mine. Even after five Agents, I skim the code myself. Reviewer can be too strict, Tester's tests can be meaningless, Debugger can point the wrong way. With a team, the last gate is human. Take that as a given, and role separation alone changes code quality — measurably.

Based on an actually running workflow plus official docs. Services and features can change — check official docs for the latest.

Originally published: April 2026 · GoCodeLab