The task was a payment service refactor. Move from one validation approach to another, across about forty files, without breaking the test suite.
I gave a single agent one prompt describing the whole job: understand the architecture, design the migration, implement it, check for security regressions, verify the tests. One context, one conversation, one agent doing everything.
It got about 60% through, produced plausible-looking code across thirty-one files, and then quietly started undoing its own earlier work. Security checks I'd explicitly asked for got skipped. Three files ended up with two competing implementations of the same function.
Nothing was "wrong" with the model. The problem was structural. I'd asked one context window to hold five incompatible jobs — architecture, security, implementation, verification, self-critique — and those jobs have genuinely different priorities. The optimizer that produces careful, conservative security review is not the same one that produces fast, decisive code edits. Forcing a single prompt to serve both means something loses.
That failure is what sent me down the multi-persona path, and it's what convinced me the monolithic prompt is on its way out for anything non-trivial. As we benchmarked in our 2026 AI Agent Harness Shootout (Claude Code vs. Antigravity vs. Grok Build), decomposing execution across specialized subagents changes everything.
What's actually happening to your context window
Three real mechanisms cause degradation in long single-prompt agents:
- Instruction dilution: If you give an agent twenty directives, it weights them roughly evenly regardless of position or importance. Add "keep answers concise" to an agent doing security analysis and you've weakened your own audit.
- Attention drift over long horizons: Models don't attend uniformly across a long context. There's well-documented degradation where information in the middle of a long context is retrieved less reliably than information at the beginning or end.
- Persona conflict: When you ask one agent to be both a cautious auditor and a fast implementer, you're asking it to optimize two different loss functions at once. The result isn't a balanced compromise — it's erratic behavior.
The multi-persona architecture
The pattern that worked for us is an orchestrator with narrow specialists, each owning a disposable context:
┌─────────────────────┐
│ ORCHESTRATOR │
│ plans, delegates, │
│ adjudicates │
└──────────┬──────────┘
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌─────────────┐ ┌──────────────┐
│ ARCHITECT │ │ SECURITY │ │ QA │
│ designs │ │ audits │ │ verifies │
│ the change │ │ the diff │ │ behaviour │
└──────┬───────┘ └──────┬──────┘ └──────┬───────┘
│ │ │
└────────────────┴───────┬───────┘
▼
┌──────────────┐
│ CODER │
│ implements │
│ (only here) │
└──────────────┘The critical property: the coder never plans and never audits itself. Those are separate contexts with separate system prompts. That's what removes persona conflict.
The persona pipeline in action
- Architect reads the codebase, produces a migration plan with explicit ordering and dependencies. Its output is a document, not code.
- Security Auditor reads the plan and the current state of the files it touches. It flags risks before anything is written — auth handling on the new path, secrets that might move, injection surfaces.
- Coder receives the plan, the security constraints, and only the files it needs. It does not implement and audit simultaneously.
- QA Verifier runs against the actual diff: tests, type checks, and a specific checklist derived from the security flags.
The security auditor's findings become hard constraints in the coder's prompt. Turning audit output into input to implementation rather than commentary after it fixed most self-reverting behavior.
Implementing subagents in Claude Code with ECC
In Claude Code, subagents are markdown files in .claude/agents/, each with its own system prompt, tool access, and model selection. Using open-source rule frameworks like Everything Claude Code (ECC) (see our interactive Everything Claude Code Architecture Deep Dive), you can instantiate production personas in minutes. To ensure third-party tools don't execute unauthorized commands, review our guide on Hardening Enterprise MCP Server Bridges.
.claude/agents/security-auditor.md
---
name: security-auditor
description: Reviews a planned change for security regressions before implementation.
tools: Read, Grep, Glob, Bash
model: opus
---
You are a security auditor. You do not write production code.
Your job is to read the proposed change plan and the current state of
every file it touches, then produce a findings list.
For each finding output:
- SEVERITY: critical | high | medium | low
- FILE: path:line
- ISSUE: one sentence
- CONSTRAINT: the specific rule the coder must follow to resolve it
Constraints become hard requirements in the coder's prompt..claude/agents/qa-verifier.md
---
name: qa-verifier
description: Verifies an implemented change against its plan and security constraints.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a QA verifier. You do not fix things. You report.
1. Run the test suite. Report pass/fail counts verbatim.
2. Run the type checker. Report errors verbatim.
3. Check each CONSTRAINT from the security audit against the actual diff.
4. Check that every file in the plan was actually modified.
Output a verdict table. Do not editorialize.Note the deliberate tool restrictions. The auditor gets Read, Grep, Glob — it cannot write. The verifier can Bash to run tests but its prompt says it doesn't fix.
Verification loops before commit
Using Everything Claude Code (ECC) hooks, you can gate git commits until a mechanical check passes:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "./.claude/scripts/gate-commit.sh"
}
]
}
]
}
}The gate script checks for a verification artifact from the QA pass and refuses the commit if it is missing or shows failures.
The real trade-offs: latency and tokens
- Latency compounds: Four sequential personas take roughly four times the wall-clock time of one agent. For a 40-file refactor that's fine; for a one-line fix it is overkill.
- Token consumption increases: Each specialist gets its own system prompt and reads of relevant files. You pay more total tokens to get substantially higher reasoning reliability. To control these costs across team fleets, deploy caching and compression proxies as explained in our guide on Cutting AI Coding Agent Costs by 60%.
- Orchestration is real code: Coordinating handoffs, verdicts, and failure fallbacks requires deliberate engineering.
Frequently Asked Questions
Why do long AI agent prompts degrade in quality? Instruction dilution, attention drift, and persona conflict compound over long context windows. The model weights directives uniformly and loses focus on earlier instructions when optimizing for both speed and caution in a single thread.
What is multi-persona AI agent architecture? Decomposing one generalist agent into narrow specialists (Architect, Security Auditor, Coder, QA Verifier), each with a dedicated system prompt, restricted tool access, and disposable context, orchestrated via structured handoffs.
What is Everything Claude Code (ECC)? An open-source collection of Claude Code persona configurations, commands, skills, and pre-commit verification hooks designed to standardize multi-agent software engineering pipelines.
Do multi-agent swarms cost more tokens than a single agent? Yes. Decomposition gives each specialist a fresh context and system prompt. Total token volume is higher, but the elimination of hallucination and rework results in a net saving on large refactoring tasks.
