Most persona files read like a LinkedIn bio: "You are a senior engineer who values clean code and clear communication." It sounds right. It also does almost nothing, because there's no checkable claim in it — an agent can violate "value clean code" in a hundred ways and never technically disagree with the sentence.
The gap between an agent that feels like a chatbot and one that feels like a colleague isn't model quality. It's whether the instructions are written to be checked or just to be read.
Identity and rules are not the same document
Persona setups that hold up over long sessions split into two files with different jobs:
- Identity (voice, values, how it talks about tradeoffs) — this can be soft. "Direct, skeptical of hype, cites sources" is fine as prose.
- Operating rules (what it must and must never do) — this cannot be soft, or it gets ignored the moment following it is inconvenient.
Mixing them weakens both. A rules file full of identity language reads as suggestion, not constraint — and agents, like people under deadline pressure, treat suggestions as optional.
Write rules as gates, not vibes
Compare:
- "Be careful about test coverage." — no agent has ever failed to comply with this, because it can't.
- "Never commit without running the test suite and confirming it's green." — this is checkable. The agent either did it or didn't.
The second form is boring to write and that's the point. If a rule can't be violated in a way you could point to and say "there, that broke it," it isn't a rule yet — rewrite it until it is.
Pre-empt the rationalization, not just the violation
This is the part that actually holds up under pressure. Agents (and people) don't break rules by deciding to; they break them by finding an exception that feels legitimate in the moment. "This change is too small to need a test." "Just this once, the deadline matters more." If you've watched an agent drift, it's usually not ignoring the rule — it's reasoning its way around it.
The fix is to name the excuse in the rule itself:
Never commit without tests passing — including "this is too simple to need a test," "the deadline is today," and "I already checked it manually."
It reads over-specified until the first time an agent tries exactly that excuse and the rule already closes the door.
Treat drift as a bug, not a retrain
When an agent misbehaves, the instinct is to re-explain in the next message. That fix doesn't survive the session. Patch the persona file instead — add the case that broke as a named exception, the way you'd add a regression test. Each patch is small, but they compound: six months of "the agent tried this and I closed it" produces a rules file that's actually been fought over, which is the only kind that holds.
What this doesn't fix
Persona files don't compensate for missing context — an agent with a perfect AGENTS.md and no access to your actual codebase conventions will still guess wrong. And no amount of gate-writing helps if the rules contradict each other; a file that says "never ask for confirmation" next to "always confirm before destructive actions" just teaches the agent that rules are negotiable, which undoes everything above.
If you want a starting point rather than a blank file: we give away the SOUL.md/AGENTS.md templates we use ourselves, free, in the Agent Starter Kit — mostly so you have something concrete to argue with instead of a blank page.
Full playbook: https://agentkitworks.com/use-cases/agent-personas
Top comments (0)