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.
