One Claude Code Agent or Many? When to Split Them Up

You need eight versions of basically the same worker. Eight writers, eight reviewers, eight personas — whatever. The instinct is to make eight agents. Copy the file, change a few lines, repeat.

Don't. Most of the time that instinct is wrong, and it costs you later.

Here's the actual decision, the rule that settles it in one question, and a real example from building this site: we needed eight distinct writer voices and shipped them with one agent.

The decision nobody frames for you

Almost every guide on Claude Code agents jumps straight to the hard fork — subagents versus agent teams, parallel versus sequential, orchestration. That's a real decision, but it's not the one you hit first.

The one you hit first is dumber and more common: I need N variations of the same job. Do I make N agents, or one agent that reads N files?

Why "just make more agents" feels right and usually isn't

Making more agents feels right because each one looks self-contained. One file, one job. Clean.

It stops being clean the moment the shared part changes. You wrote eight agents that all write articles the same way, differing only in tone. Now you want to change the article structure. Congratulations — that's eight edits, and you'll miss one. Every shared rule you copied is now a maintenance debt you pay eight times.

Duplication isn't free. It just defers the bill.

The one question that decides it: what actually changes?

Look at your N variations and ask what is actually different between them. Not what feels different — what literally changes in the instructions.

Varies by data → one agent + data files

If the only thing that changes is content — a tone of voice, a set of rules, a list of facts, a persona — that's data, not logic. The job is identical.

A persona is just a chunk of a system prompt you're swapping in. There's no reason to clone the whole agent to swap a paragraph. Put the variable part in a file, and have one agent read the right file.

Varies by tools, permissions, or workflow → separate agents

If the variations need different tools, different permissions, or a genuinely different sequence of steps, that's logic. That's a different job wearing a similar name.

A code-reviewer that only reads files and a deploy-agent that can run shell commands are not two personas of one worker. They have different blast radii. Split them, and scope each one's tools down to what it needs. That isolation is the entire point of separate agents — a writer agent should not have the keys to your deploy pipeline.

A real example: 8 writers, 1 agent

This site is written by eight named writers, each with a different voice and set of opinions. You're reading one of them.

What we almost did: 8 near-identical agents

The obvious build was eight agent files — marcus-writer, sam-writer, and so on. Each one a content-writer with a different personality bolted on.

Eight files. Every one of them carrying the same rules about frontmatter, structure, fact-checking, and SEO. Change the house style once, edit it eight times.

What we did instead: 1 content-writer + 8 persona files

Instead there's one content-writer agent and eight plain markdown files — one per writer — holding the only thing that actually differs:

content/writers/
  marcus-vale.md     # voice, opinions, beat
  sam-okafor.md
  caleb-north.md
  ...

Each file is just data:

---
name: "Marcus Vale"
role: "The craft & ownership purist"
voice: "Blunt, dry, technical. No fluff, no hype. Short declarative sentences."
opinions:
  - "Own your stack — avoid lock-in at all costs"
  - "If you can't export it, you don't own it"
beat: ["CLI agents", "local models", "open-source tools"]
---

The agent reads the assigned file and writes in that voice. The writing logic — structure, honesty rules, frontmatter spec — lives in exactly one place.

Why the data version won

Adding a ninth writer is one new file. No new agent, no copied rules, nothing to keep in sync. The house style changes in one spot and every writer inherits it instantly. And the personas became reusable — the same files now drive a byline, an author page, and a "guest tip" block, because they're data, not buried in an agent's prompt.

Eight cloned agents would have given us none of that. Just eight copies of the same chores.

How to wire the persona-loading pattern

It's three moves. Nothing clever.

1. Put the stuff that varies in plain data files

One file per variation, holding only what differs. Markdown with frontmatter, JSON, whatever you'll read easily. Keep the shared logic out of these — they're data.

2. Let the caller pick which one

Something has to choose the persona. For us it's the article brief: it names a writer slug, and that slug maps to a filename. A pipeline step upstream makes the choice so the agent doesn't have to guess.

3. The agent reads the file and adopts it

The agent's instructions say: read the named file, write in that voice. That's it. The agent is a stable engine; the file is the swappable cartridge.

# content-writer agent, in plain terms
Read content/writers/<slug>.md.
Write the article in that writer's voice, using their opinions.
Everything else — structure, rules, format — is the same every time.

When many agents IS the right answer

Don't take this as "always use one agent." Sometimes multiple Claude Code agents are exactly right. Split into separate agents when:

• The tools differ. One variant needs web search, another needs shell access. Different tools, different agents — and scope each down.
• The permissions differ. Anything that can write, deploy, or spend money should be its own agent with its own tight leash.
• The workflow differs. Not a different voice doing the same steps, but a genuinely different sequence. A researcher and a publisher are different jobs.
• You want isolation. Separate agents get separate context. If you need one variant's work walled off from another's, that's a real reason — and it's where orchestration patterns start to matter.

The test: if you can describe the difference as "it says things differently," it's data. If the difference is "it can do different things," it's a different agent.

Rule of thumb (copy this)

Varies by data → one configurable agent + data files. Varies by tools, permissions, or workflow → separate agents.

Start with one. Reach for more agents when a variant needs to do something the others can't — not just say something differently. You'll maintain a lot less, and the things you split will be split for a reason that actually holds up.