Write Your AI Agent Doctrine, Not Prompts

I run one AI agent across my whole life, business and personal. What makes that work is not the model. It is that each system is written down in a form the agent reads before it touches anything.

The hard part of building with agents now is not capability, it is reliability. The instinct is to reach for a smarter model, or a sharper prompt. In my experience the reliability problem is almost never the model or the prompt. It is that the system the agent is supposed to run was never written down in a form it can read. So here is the pattern I use. It is two layers, and once they are in place a genuinely capable agent stops reinventing your business and starts operating it.

01Why does a capable AI agent keep getting your system subtly wrong?

Because it is reasoning about your system from scratch instead of reading it: drop a capable agent into a cold session and it rebuilds your logic from first principles, and it gets the subtle parts wrong.

It theorizes about what a metric means when you already defined it. It contradicts a rule you settled three weeks ago. It re-proposes work that already shipped. It reinvents a process you have refined over months, and because the model is fluent, it does all of this without hesitation. You end up correcting it every session, and the correcting is worse than the error, because it quietly teaches you not to trust the output. The smarter the model, the more plausible the wrong reconstruction looks. Intelligence is not the missing piece. The written system is.

02What actually fixes it: make the agent read the system before it reasons about it

The fix is two written layers, doctrine and a primer: doctrine is the canonical truth of a process, and a primer is a one-command load of the right slice of it, so the agent reads the system before it reasons about it.

Doctrine is the source of record: what exists, how you decide, what the current state is. A primer is an orientation step, one command that loads the right doctrine at the start of a session, so the agent reads before it reasons. Doctrine is what is true. The primer is how the agent loads it. The doctrine is not one document, it is a small set of files, which we will get to; the primer is the one command that loads the right ones. The whole pattern enforces a single rule, and it is worth saying plainly:

Read the system before you reason about it.

That is the entire idea. Everything below is just how to make "the system" a thing that can actually be read.

03What is doctrine, and what are its four parts?

Doctrine, the first of the two layers, is not a single document. It is four files that each do one job and never mix: a map of what exists, the rules for how you decide, the current state, and the dated history.

Each managed system gets one folder, and inside it, four kinds of file:

• The map (a README): what the pieces are, where each lives, how the thing is operated. It is the front door, and it routes to the other docs instead of duplicating them. Anyone, human or agent, who has never seen the system reads this and knows the shape.
• The rules (a playbook): the decision rules, thresholds, guardrails, and definitions. The "how we think about this," stable across runs. Number the sections so the other docs can cite them. If it is a judgment you keep having to restate, it belongs here.
• The state (an operating log): the current config plus a change log. This is the piece that tells the agent what NOT to re-propose. Without it, every session re-does shipped work; with it, the agent knows the high-water mark and picks up where the last run left off.
• The history (dated records): the "why did we do that" trail, six months out. These accrete and are never edited.

The single biggest mistake is one giant document that mixes rules, state, and history. It rots, because the state goes stale while the rules stay put, and once one part is wrong nobody trusts any of it. Keep the four jobs separate and each stays trustworthy on its own clock.

04What is a primer, and why must it load and then stop?

A primer is a single command that loads the right slice of doctrine, orients the agent, and then stops. It never does the work, because the moment it starts doing the task it is acting on half-loaded context.

The primer reads the map and the rules, names the data sources the agent should read from, restates the guardrails, prints a tight orientation, and stops. The actual work is a separate command, a worker, that proposes changes. Then a human approves. Then the worker executes. Three separate things:

The primer loads. The worker executes. An approval gate sits between the proposal and any real change.

That separation is not bureaucracy, it is the safety model. A new lever starts gated: the worker proposes and a human clears it. As the agent proves itself, it earns its way past the gate on the moves that are safe to hand over. Collapse the primer and the worker into one step and you get an agent acting on half-loaded context, which is exactly the fluent-and-wrong failure you were trying to avoid.

05How does the agent know what your source actually means?

An agent can only use a source correctly if it understands what is in it, so document the source itself, clearly enough that the agent reads what each part means instead of guessing.

When the agent reads a source, your data, a report, a system it pulls from, it needs to know what each part actually means. Write that into the source itself and the agent reads it and gets it right. Leave it implicit and the agent guesses from a label, and a confident guess about what something means is exactly how you get a confident wrong answer. So document the source thoroughly. The clearer it explains itself, the less the agent has to invent.

06How do you build one for your own process?

Start with one folder and the smallest working set: a map, a playbook with about five real rules, a state log, and a primer that loads them, then grow the rules and the audit trail as you run it.

Concretely:

• Write the map first. Forcing yourself to list every piece, what it is and where it lives, is what makes you actually enumerate the system.
• Write the playbook next, starting with the handful of judgments you keep re-explaining. Add the thresholds and guardrails. Number the sections.
• Write the state log: current config, IDs, an empty change log, and the open watch items. Update it whenever state changes from then on.
• Document your sources so the agent reads them, not guesses.
• Write the primer last, pointing at the files you just wrote, and hold the load-and-stop discipline.

Do not over-build. One system is one folder with those four artifacts and a primer. Resist inventing a grand "platform" umbrella until a second system genuinely earns the same treatment. A map, five real rules, a state log, and a primer is already a complete, working system.

07Isn't this just documentation with fancier names?

Partly, but the difference is the reader: documentation is written for a person who fills the gaps with judgment, and this is written for an agent that fills in nothing and acts on exactly what is there.

A wiki can be vague and still work, because a person reads it and supplies the missing judgment. An agent does not. It acts on exactly what the doctrine says, so the four-way separation and the load-and-stop discipline are not ceremony, they are what stop a machine from filling the gaps with a confident guess. Call it documentation if you like. It is documentation held to a standard most documentation never is.

08Doesn't hand-written doctrine just go stale?

It can, and a doctrine that has drifted from reality is worse than none, because the agent trusts it completely and acts on it, so keeping it true is ongoing work, not a write-once task.

This is the real cost of the approach, and its honest weak point. The map and the rules change only when the system or your decisions change, so they stay stable. The state is the part that moves, which is why it lives in its own file you update every run, and why the numbers that change belong at their source rather than pasted into a doc. None of that is glamorous, but it is the price of an agent that can act on what it reads. Skip it and you have handed a confident worker a manual that is quietly wrong.

09Why this matters more as you hand agents real authority

The more an agent can do on its own, the more a single wrong line in its context becomes a wrong action, so the written truth it reads from stops being documentation and becomes the safety system.

When an agent only advises you, a wrong line in a doc costs you a bad suggestion you can wave off. When an agent acts, on spend, on prices, on a live system, that same wrong line becomes a wrong move it makes for you, confidently, while you are not looking. That is the real reason this is not busywork you do once and forget. The doctrine is the thing that has to be true, and kept true, for the autonomy to be safe. That is what the discipline buys: read the system before you reason about it, document your sources so the agent reads them instead of guessing, and separate what the agent loads from what it is allowed to do.