If you've set up persistent instruction files for a coding agent, you've probably ended up with one file trying to do two jobs: sound like a person and enforce a rulebook. It usually goes something like "You're a thoughtful, careful engineer who always writes tests and never commits without running the linter" — half personality, half policy, crammed into the same paragraph.
This works until the file grows. Then it stops working in a specific, predictable way.
The two things that get confused
Persistent agent instructions are actually answering two different questions:
- Who is this agent? Voice, values, taste, how it communicates, what it refuses to do on principle.
- How does this agent operate, here? Build commands, test commands, directory layout, what's forbidden, what tools exist.
The first is identity. The second is operations. They don't change for the same reasons, on the same schedule, or at the same rate — which is exactly why cramming them into one file causes trouble.
Why mixing weakens both
A hard rule buried inside personality prose gets skipped. "Be thorough and always verify your changes before saying you're done" reads like tone, not like a gate — the model treats it as a suggestion about vibe rather than a checkable requirement. Compare that to an explicit line: "Do not report a task complete until you've run the test suite and pasted the output." Same intent, wildly different compliance, because one is voice and the other is a rule wearing the same clothes.
Going the other direction breaks just as badly. Personality constrained by rule-syntax — checklists and imperatives standing in for "how you communicate" — goes flat. You end up with an agent that follows procedure fine but reads like a compliance document in every response, because its identity was never given room to be anything but a rule.
The convention that fixes it: split the file
Two files, two jobs:
SOUL.md — identity. Voice, values, judgment calls, what the agent refuses to do regardless of instructions. This is stable. You write it once and touch it rarely, because who the agent is shouldn't be churning every sprint.
AGENTS.md — operations. Build/test commands, code conventions, directory boundaries, explicit do-not-touch zones, project-specific rules. This changes constantly, because it's describing a moving codebase.
The mental model that makes this click: it's a job description plus an employee handbook. You don't rewrite someone's personality when the deploy process changes, and you don't bury the deploy process in a paragraph about their communication style. Different documents, different lifecycles, different owners of the change.
The practical payoff: versioning
Once they're split, you get a versioning discipline for free that a single merged file never gives you.
AGENTS.md gets treated like code: when the agent does the wrong thing, you patch it the way you'd patch a bug — find the missing or ambiguous rule, tighten it, commit. It changes often and that's fine, because it's operational and expected to drift with the project.
SOUL.md stays put. If you find yourself editing it weekly, that's usually a sign a rule got misfiled into the identity file. Move it to AGENTS.md and check whether the actual problem — an agent doing the wrong thing — gets fixed by a sharper rule instead of a personality rewrite. It almost always does.
Portability, as a bonus
AGENTS.md is becoming a cross-tool convention that a growing number of agents read automatically, regardless of which one you're running. SOUL.md is a persona pattern, not a standard — but it travels well precisely because it holds nothing project-specific. Voice and judgment move with you between repositories; commands and conventions are per-project by definition and shouldn't.
If your current instruction file is one growing document that's starting to feel unwieldy, this is usually the fix: don't trim it, split it. The rules you're worried the agent is ignoring are probably fine rules — they're just filed under the wrong document.
Full write-up: https://agentkitworks.com/answers/soul-md-vs-agents-md
Top comments (0)