The instruction file that runs my codebase started as a junk drawer. The rules that ended up mattering weren't the ones I expected.

A note on credit before I start: most of what follows isn't original to me. I picked up these ideas from other engineers sharing what worked for them — scattered across Twitter/X threads, blog posts, and conversations — then tested them against my own codebase to see what actually held up. This is a synthesis, not an invention. Where something came from the community rather than from me, I've tried to say so. Consider it a thank-you to everyone quietly posting what they've learned.

The first time I wrote an AGENTS.md, I treated it like a README's annoying cousin. Tech stack, a few style notes, a line begging the agent to run the tests. Then I watched the agent ignore half of it and confidently do the wrong thing with the other half.

So I kept editing. Months later, the file looks nothing like where it started. And the surprising part is which rules earned their place. It wasn't the formatting conventions or the careful style guidance. It was a small number of rules that fight an agent's worst instincts, plus one hard lesson about the difference between asking and enforcing.

Here's what I found actually mattered.

The first rule isn't about code. It's about permission to stop.

The very first thing in my file has nothing to do with syntax. It tells the agent that when something is unclear, it should stop and ask. State your assumptions. If two interpretations exist, name both instead of silently picking one. If a simpler approach exists, say so.

I put this first because the default failure mode of a coding agent isn't bad code. It's confident code built on a wrong reading of an ambiguous request. Left alone, a model resolves ambiguity quietly and keeps going, and you don't find out until you're reviewing two hundred lines that solve the wrong problem.

What surprised me was that the agent needed permission to stop. Without it, the model optimizes for looking helpful, and looking helpful means producing something rather than admitting confusion. Telling it that stopping to ask is the desired outcome — not a failure — changed its behavior more than any other single line.

The lesson generalized: an agent will fill silence with confidence unless you tell it that "I'm not sure" is an acceptable answer.

Most of the useful rules just name a bad habit and forbid it

Once I started paying attention, I noticed that my most valuable rules all had the same shape. Each one named a specific, predictable bad instinct and told the agent not to do it. None of them were clever. They were just earned.

Agents over-build. Ask for a function and you can get a configurable framework with options nobody requested. So one rule is blunt about it: minimum code that solves the problem, nothing speculative, and if you wrote two hundred lines where fifty would do, rewrite it. Naming the tax is what keeps it from being paid.

Agents over-reach. An agent that helpfully reformats the whole file alongside its actual change turns a ten-line diff into a two-hundred-line one you can't safely review. So another rule constrains the blast radius: touch only what you must, match the existing style even if you'd do it differently, and make every changed line trace back to the request. This one is really about protecting review, not code. A diff you can't read is a diff you can't trust.

The rule I'd most recommend stealing is one I didn't appreciate until it bit me. When an agent finds two competing patterns in a codebase, its instinct is to find a middle path that honors both. The result belongs to neither pattern and confuses everyone who reads it later. So the rule is: don't average conflicting patterns. Pick one, explain why, flag the other for cleanup. Average code that satisfies two contradictory rules is the worst code in the repo.

There's a companion to all of these that I keep coming back to: if the agent can't explain why existing code is shaped the way it is, it should ask before adding next to it. "Looks unrelated to me" is the most expensive assumption in any mature codebase. Most subtle breakages come from changes that looked perfectly isolated to the person making them.

The lesson that reshaped the whole file

If I could keep only one thing I learned, it's this, and it took the longest to accept.

I once had a hard requirement written in plain, unmissable language at the top of the file. The agent still skipped it sometimes. Not often — just often enough to cause real problems. When I dug into why, the answer was deflating in its simplicity: models drift from instructions. A rule in a markdown file is a strong suggestion, not a contract. Over enough runs, any instruction gets ignored eventually.

That one realization split my entire file into two tiers.

There's guidance — the style preferences, the philosophy, the "prefer this over that." Guidance lives in prose and gets followed most of the time, and most of the time is fine for that category.

Then there's the stuff that has to hold every single time. And what I learned is that this stuff does not belong in prose at all. If something absolutely must happen, don't rely on instructions. Enforce it. Put it in a hook, a script, a CI check — something deterministic that makes the violation impossible to merge, not merely discouraged.

My file still says "run the checks before you call it done." But the real guarantee isn't that sentence. It's that CI fails on lint errors no matter what the agent intended. The instruction is a courtesy. The gate is the guarantee.

The practical test I use now: every time I write "always" or "never" in an instruction file, I ask whether there's a mechanism enforcing it. If there isn't, I don't have a rule. I have a hope.

Make the agent prove it, not promise it

Two more rules in the file are really about the gap between "I did it" and "it works."

The first changes how a task is framed. Instead of "add validation," the instruction is to define what success looks like and loop until it's met: write tests for the invalid inputs, then make them pass. "Fix the bug" becomes "write a test that reproduces it, then make it pass." A vague directive becomes one with a finish line the agent can check itself against, instead of declaring victory on vibes.

The second is blunt about trust: don't claim tests pass from memory — re-run them. I added this after watching the agent report a clean run that wasn't, and after watching sub-agent reviews invent bugs that didn't exist in the source. Both are the same failure: a claim untethered from a fresh check. So the rule ties every claim back to a command actually run, and tells the agent to verify a reported bug against the real code before acting on it.

The principle underneath both: trust the check, not the claim. An agent's confidence is not evidence.

Keep the laws out of the manual

One structural decision kept the whole file maintainable: my AGENTS.md doesn't try to contain the architecture.

The structural laws — dependency direction, frozen contracts, the boundaries that can't be crossed — live in a separate constitution document. The working file just points at it: read this before you add a package, cross a layer, or touch anything safety-critical. And it's explicit that if a change conflicts with the constitution, the move is to refactor or open an amendment, never to slip in a violation to ship faster, because that cost compounds.

The reason to separate them is pace. The working manual is full of conventions and gotchas that change constantly and should be edited freely. The constitution holds laws that should be slow to change and mechanically enforced. Cram both into one file and the stable laws get buried under operational churn. Keep them apart, and each can move at its own speed.

The takeaway: things that change weekly and things that should never change don't belong in the same document.

Write down the scars

The back half of my file is the part I'd most encourage every team to keep: a running log of non-obvious lessons. Not conventions — scars. The specific things that cost someone half a day and would cost the next person the same half-day if they weren't written down.

They're deliberately concrete. The database pseudo-column that isn't selected by default, and the exact error you get when you forget it. The streaming API that keys its events by index instead of ID and arrives in a surprising order. The native dependency that silently fails to compile unless it's on an allowlist. None of these are principles. They're landmines, mapped.

This section matters more with agents than it ever did with people, because an agent has no scar tissue. A human who lost a day to something tends to remember it. An agent will rediscover the same landmine the hard way every single time, unless the knowledge is written where it'll read it. That's the quiet value here: it's how a codebase's painful, accumulated knowledge gets inherited instead of relearned.

Every unexpected hour you lose is only worth paying once. Writing it down is how you make sure of that.

What the file is really for

After all the editing, here's how I think about it now. This file isn't a style guide. The formatter handles tabs and semicolons. What the file actually does is encode judgment — the judgment that used to live only in the heads of the few people who'd been around long enough to have it.

The rules that matter are the ones that counteract an agent's predictable instincts: over-building, over-reaching, guessing silently, blending conflicting patterns, claiming success it never verified. And the most important distinction in the whole file is the line between guidance you state and guarantees you enforce.

So if you're writing one of these, that's where I'd spend the effort. Give the agent permission to stop and ask. Name the bad habits you keep seeing and forbid them by name. Move anything that must always hold out of prose and into a check that fails the build. Point at your architecture instead of restating it. And keep a growing log of your scars, because the agent will step on every landmine you don't map.

The formatting rules write themselves. The judgment is the part worth writing down.