Why this matters beyond the homelab: As agents get filesystem and API access, the document defining their behavior becomes operational configuration rather than flavor text. It deserves the same treatment as any other config: version control, deliberate changes, and honest assessment of which parts actually do anything.
What the File Is
My agent runs on a framework that loads a persona document at session start. It sits in front of every conversation and shapes tone, priorities, and constraints.
The naming is thematic. The function is not: it is the closest thing the agent has to a configuration file for behavior, and it is the highest-leverage text in the entire system, because every other instruction the agent receives is interpreted through it.
The First Version Was Mostly Decoration
My first pass was heavy on character. Voice, personality, in-universe framing consistent with the rest of my lab’s naming scheme. Fun to write.
Almost none of it changed what the agent did.
Persona instructions shape how output is phrased. They have very little effect on whether the agent calls a tool correctly, reports honestly, or refuses to guess. Those behaviors come from explicit operational constraints, and my first version had approximately none.
The rewrite inverted the ratio. A short section establishing voice, and a much longer section establishing rules about how work gets done.
The Rules That Actually Changed Behavior
On tool use, written after a specific failure. The agent had been reporting successful file operations that never happened, inventing filenames and directory listings under load. The persona now says, directly:
- Call the tool. Do not describe calling the tool.
- Never report success until the tool has returned a result.
- If a call fails, say it failed. Do not substitute a plausible result.
- Never produce example output in place of real output.
Blunt and repetitive on purpose. Subtle phrasing gets averaged away under load.
On uncertainty. Instructions to say “I do not know” and to distinguish between what was read from a real source and what is being inferred. Without this the default is confident completion, which in an operations context is worse than no answer.
On scope. What the agent is for, and explicitly what it is not for. Mine is for reasoning about infrastructure: reading documentation, correlating alerts, explaining configuration. It is explicitly not for deterministic file transformation, because that is a job for bash and routing it through a language model only introduces failure modes.
On verification. After any operation claiming to change state, report how that change can be independently verified. Not “done,” but “done, confirm with this command.”
What Did Not Work
Long rules get diluted. A paragraph of nuanced guidance is less effective than one short imperative sentence. The model appears to weight brevity and directness heavily.
Rules do not survive degraded inference. The most important limitation, and the one worth being honest about: when the model was under sustained load or deep in a long context, it fabricated tool results despite explicit instructions not to. The persona reduced frequency. It did not provide a guarantee.
A persona cannot fix an architectural problem. The fabrication issue was ultimately solved by moving deterministic work out of the agent entirely, into bash scripts that cannot hallucinate. The persona rules helped. The architecture change fixed it.
That is the honest framing: the persona file is a strong default, not an enforcement mechanism. Anything that genuinely must not happen needs a structural guarantee, not an instruction.
How I Validate Changes
Persona edits are hard to evaluate because the effect is probabilistic and often subtle. What works:
Change one thing at a time. Rewriting the whole file makes it impossible to attribute any behavior change.
Test against the failure you are targeting. For the tool-use rules, I re-ran the operations that had produced fabrication. For the uncertainty rules, I asked questions the agent could not possibly know the answer to and checked whether it admitted that or invented one.
Use checkable prompts. Ask for something with an unambiguous verifiable answer, like the current date, and confirm the response matches reality. A wrong timestamp tells you instantly whether tool execution is real.
Keep it in version control. It is configuration. It gets committed, with a message saying what behavior the change was meant to address, so that six months from now I can tell why a rule exists rather than deleting it as clutter.
The Structure I Settled On
Roughly, in order:
- Identity and scope, short. What this agent is, what it is for, what it is not for.
- Operational constraints, longest section. Tool use, verification, uncertainty, refusal to guess.
- Environment context. Enough about the infrastructure to reason usefully, without duplicating the documentation it can retrieve on demand.
- Voice, shortest section. Tone and phrasing, kept last because it is the least important.
Ordering matters more than I expected. Instructions earlier in the document appear to carry more weight, so operational rules go above personality rather than after it.
Takeaways
Persona files are configuration, not flavor. Version control them and change them deliberately.
Operational constraints change behavior, tone does not. Weight the file accordingly.
Be blunt and repetitive on rules that matter. Nuance gets averaged away.
Instructions are defaults, not guarantees. A degraded model does not reliably follow its own persona.
Structural fixes beat instructional ones. If something must not happen, remove the capability rather than requesting restraint.
Validate with checkable prompts. Something with a verifiable answer tells you immediately whether the agent is really executing.
Order the file by importance. Constraints first, personality last.
Related: Jocasta: Retiring My Custom Bot for a Real Agent Framework | My Agent Told Me It Wrote Twelve Files | The Fleet Codex Pipeline