Everyone's writing agent instructions now. System prompts, CLAUDE.md files, cursor rules, AGENTS.md, custom GPT instructions, prompt templates — the whole zoo. And almost all of it is the same kind of document: a description of the world the agent operates in.
That's the wrong document.
Your agent can read code. It can search files. It can grep for patterns and infer conventions from context. Anything descriptive — what exists, how things are structured, what the stack looks like — the agent can figure out on its own. You're writing a tour guide for something that can already read the map.
The document your agent actually needs is the one it can't derive from the code: your intent. What you decided and why. What's never allowed. What must always be true. The decisions that live in your head and nowhere else — until you write them down as laws, not observations.
That's the difference between describing and prescribing. And it's the difference between agents that help and agents that drift.
The Bug You Already Fixed, Fixed Again
My co-founder Mark builds our backend — mirror-harness, an agent orchestration layer. Heavy brownfield, tens of thousands of lines, cross-cutting concerns everywhere. A few weeks ago he reviewed a long list of findings an agent had produced after scanning the repo. Forty items, ranked by severity.
Half were noise — the agent had re-derived conventions from scratch, proposed refactors that already existed, flagged "bugs" that were intentional. Standard stuff.
But the other half was the interesting failure. The agent kept "discovering" problems Mark had already solved months ago. Permission checks bypassing the artifact gateway. Direct Firestore writes instead of the write pipeline. Cache invalidation where there should be cache-fresh writes. Every time the agent hit a shared concern, it invented a new solution — because in isolation, inventing looked like the right move.
Mark's take: "It's like trying to plug a hole in a ship. The agent's gonna try and fix that permission issue by reinventing the permission situation when in reality, the system is designed correctly — the agent just forgot to check the gateway."
That's not a model problem. Mark had the decisions in his head. The code had the results. But nobody had written down the rules in a form that said: this is the law, and if the code doesn't match, the code is wrong.
What Descriptive Looks Like (And Why It's Not Enough)
A descriptive doc answers: "What does this look like?"
- CLAUDE.md describing your tech stack, file layout, naming conventions
- README explaining how to run the project
- System prompts telling the agent "you are a helpful assistant that works with our React + FastAPI stack"
- Cursor rules saying "here's the component style we use in this folder"
- Custom GPT instructions listing the tools available and the domain you operate in
Useful? Sure. New engineers need orientation. Agents use it to bootstrap context. But here's the fatal flaw: descriptive docs describe the current state, not the intended state. If the code drifts, the description drifts with it. A descriptive doc never contradicts the code — so it can never catch the code being wrong.
An agent can do all of this work itself. Point it at a codebase and ask "what's the architecture here?" — it'll give you a perfectly fine descriptive summary. You're authoring the thing the model is already good at.
A prescriptive doc answers: "What must always be true, and what is never allowed?"
- "All LLM provider calls go through
common/llm_gateway/. No directgenai.Client()calls anywhere else in the codebase." - "Artifacts are immutable after creation. If you need different data, create a new artifact. Never update in place."
- "Secrets are passed into function sandboxes via environment injection. They are never printed, logged, or returned to the user."
These are invariants. Laws, not observations. The kind of thing that makes you say "wait, this code is wrong" when you read the code next to the doc — because the doc didn't move, so the code is the one out of compliance.
The agent cannot derive these. They're not in the code — they're in your head. They represent the decisions you made, the traps you already fell into, the architecture you chose on purpose. Writing them down is the act of externalizing your expertise into a form the agent can actually enforce.
Caller or Contract — The Only Question That Matters
Once you have a prescriptive doc, everything simplifies. Mark's framing: any piece of code that touches a shared concern is a caller. Every caller is in exactly one of two states:
- Following the contract. Ship it.
- Breaking the contract. Then either the code is wrong and needs to be fixed, or the contract is wrong and needs to be updated — and every other caller updated with it, in the same PR.
No third option. No "this case is special." No "we'll clean it up later." No "but the client is right there, it's simpler."
"Caller or contract?" — one question, two answers. Binary. That's the whole point. When you apply that question to every diff that touches a shared concern, drift has nowhere to hide.
This works for agent instructions at every level. System prompt says the agent must always cite sources before making claims? Then every response either cites sources or violates the contract. Agent instructions say all database writes go through the ORM? Then every raw SQL call is a violation, not a creative shortcut. The binary collapses "interesting suggestion" into one of two known workflows.
The Currency That Scales
Here's where it gets powerful.
Mark's workflow once a contract violation is confirmed:
- Open the prescriptive doc.
- Spin up a sub-agent: "Read
ARTIFACT_GATEWAY.md. Find every caller in the codebase that violates an invariant from that file. Ranked list. No fixes." - Sub-agent returns 8 findings. Three real, five noise.
- Spin up three more sub-agents in parallel — WebSocket layer, resolver layer, tool handlers. Same contract, different slice.
- Merge findings, pick the real ones, add to the plan.
This only works because the prescriptive doc is a currency of intent. Mark's words: "It's just a currency to exchange the principle without having to re-explain it. It's just documentation, you know?"
"Just documentation" — but documentation that carries decision authority. You hand a sub-agent a link and trust that every agent who reads it gets the same laws. No drift across agents, no re-explaining, no context loss.
Descriptive docs don't work as currency. A CLAUDE.md describing your project layout isn't something you hand an agent and say "check every file for violations" — there's nothing to violate. It's a map, not a constitution. A prescriptive contract is a constitution. You can audit any code against it and get a binary answer.
This is the unlock: prescriptive docs let you parallelize judgment across agents without losing coherence.
Why Scoped Rules Miss the Point
Teams often try to solve this with folder-scoped rules — cursor rules per directory, CLAUDE.md per module. "Rules for auth go in src/auth/, rules for the API in src/api/."
Doesn't work for cross-cutting concerns. And cross-cutting concerns are exactly where drift lives.
Artifact permissions in our codebase need to fire in the WebSocket layer, the HTTP API, the background poller, the chat handler, the tool dispatcher, the resolver, the caching layer — ten different folders. A folder-scoped rule says "if you're in this folder, do this." It can't say "if you're doing this thing, do this — no matter where you are."
The right mental model: the rule applies anywhere the thought happens. Not anywhere the file lives. The concern travels across folders, so the contract has to be addressable by name, not by location.
This is true beyond codebases. System prompts for customer-facing agents have the same problem. You can scope rules by conversation type or user role, but the invariants that matter — data privacy rules, escalation policies, tone boundaries — apply everywhere. They need to be stated as laws the agent checks before acting, not descriptions of how the agent usually behaves.
The Drift That Looks Reasonable
Each instance of drift looks perfectly fine in isolation. An engineer (or agent) sees a permission bug. The gateway is two folders away. The client is right here. "I'll just fix it locally, faster."
Six months later, forty places handle permissions differently. None agree on what a "viewer" is. A permission change that should be a single-line gateway edit is now a forty-file refactor. The agent that "fixes" it will generate forty patches — in forty slightly different ways.
This is where people blame the LLM. "So inconsistent!" No. The agent is being perfectly consistent: it's reading the code and the descriptive docs, which say "there are forty different ways to check permissions here." The agent mirrors the drift. The drift was introduced by humans who didn't have a prescriptive contract to point at.
The same pattern shows up in non-coding agents. A support agent whose instructions describe the refund policy ("we typically offer refunds within 30 days") will interpret "typically" differently in every edge case. A support agent whose instructions prescribe the policy ("refunds are issued for requests within 30 days of purchase. No exceptions without manager approval.") gives you a binary to audit against.
The fix is not better models. The fix is prescriptive instructions.
The Autonomy Ceiling
Here's why this matters beyond drift prevention.
The number of well-defined prescriptive contracts in your system sets the ceiling on how much autonomy you can grant your agents. Two contracts? Agents operate safely on two concerns. Ten contracts, ten safe concerns. Fifty contracts covering every cross-cutting invariant, and now you can seriously think about agents doing work that gets auto-reviewed by other agents against the contracts — with a human involved only when a contract needs to change.
Mark's North Star: "An architecture of contracts where agents are free to build as long as they check the contracts. Then when we get a pull request from an agent, another agent checks contract compliance."
This isn't limited to code. It's the same pattern for any agent system. If your sales agent has prescriptive rules about pricing authority, it can negotiate autonomously within those boundaries. If your ops agent has prescriptive rules about escalation thresholds, it can triage without a human until it hits the boundary. The contracts are the autonomy.
Every time you skip writing a prescriptive doc for a concern, you're buying short-term velocity at the cost of long-term autonomy. Every time you write one, you're unlocking a piece of your system for agents to operate safely without you.
What to Do Monday Morning
If your agents are drifting — reinventing solutions, inconsistently applying rules, producing work you keep correcting the same way:
- Pick the one concern causing the most "I already decided this" frustration. The thing you keep explaining to agents (or new engineers) that should already be settled.
- Write the prescriptive doc. State invariants as laws. "All X go through Y. No direct Z anywhere." Not "we usually" or "most of the code does."
- List anti-patterns with concrete wrong-way / right-way examples. Every anti-pattern should be a mistake that actually happened.
- Fix every existing violation in one pass. If you skip this, the contract is a lie from day one.
- Update the contract every time you change the concern. A stale contract is worse than none — it actively lies to every agent that reads it.
Then give your agent one instruction: "Read the contract. Every action must follow it or propose a change to it — tell me which."
The drift stops. The hundred inventive solutions collapse into two known workflows. The agents become reliable — not because they got smarter, but because you finally wrote down what you actually meant.
Mark Freedman and William Van Buskirk are co-founders of Make Yourself AI. They build mirrored agents for operations-heavy businesses — and spend a lot of time arguing about which markdown files actually matter.