An agent.md that is out of date is worse than none
The file you write to stop repeating yourself to a coding agent goes stale, and then the agent obeys it anyway. Mine told a lie about my own repository today.
If you keep an agent.md or a CLAUDE.md at the root of a project, the rule
worth adding to it is this one: anything a machine could check does not belong
in that file. Facts about the code go stale, and an agent obeys a stale
instruction with exactly the same confidence it obeys a good one. A missing rule
gets discovered. A wrong one gets followed.
That happened here today, which is why I am writing it down.
The file, and why people write one
Fabien Sanglard published a short piece on 21 August 2026 about the agent.md
he keeps in his projects. The history in it is familiar. He tried an LLM in
mid-2025 on an mDNS implementation in Rust and the code would not compile. He
came back in January 2026 and it found him an obscure bug in the polling crate,
but what it wrote was spaghetti with no comments and no structure. By March he
was using agentic IDEs and reviewing the output of what he calls an infinitely
patient junior: don’t use magic numbers, add a comment, keep function names
short. The quality got close to his own. The cost was saying it again in every
new session.
So the file is a way of saying it once. His rules are worth reading in full, and three of them I took straight:
Avoid superlatives and praise. Stop telling me I am absolutely right. Give me the cold hard truth.
Don’t touch blocks of code unrelated to the feature you implement.
If the prompt indicates that a bug is being fixed, don’t write the fix right away. First write the test. Observe it failing. Then write the fix. And observe the test passing.
He also names the problem that makes any long file leaky. It is called context dilution, from the Lost in the Middle paper: as the context grows, a model attends less to what sits in the middle of it than to what sits at either end. His two answers are to start a new session per feature and to say “reload agent.md” out loud when the quality drops.
What mine is for
This site has four of these files, one per part of the repository. They are not style guides. Almost everything here is written into markdown by an agent I am talking to, and the rules exist to stop that agent destroying the one thing the site claims.
Never invent a fact. Not a date, a number or a name. Ask, or leave the field empty. Counts are derived from the files on disk and never typed. The capture time on an entry comes off Telegram’s clock and never off my hand. Every sentence a reader sees is mine, in the first person.
Sanglard’s worst case is code he has to clean up. Mine is different in kind. An agent that has not read those rules can write an entry that passes the schema, builds without a warning, reads well, and quietly contains a date that nobody checked. That is not messy code. That is the site failing at the only thing it promises.
The lie in my own file
The root file here said, until this evening, that src/pages/ does not exist
and that building the pages was the next piece of work. It has existed for some
time. There are pages for days, notes, things, threads, search, About, /now/,
a 404 and an RSS feed.
The sentence was true when someone wrote it. It stopped being true and nobody noticed, because nothing checks it. I found it by accident: I went to start the dev server and the directory was already there.
An agent reading that paragraph believes it before it looks, the same way it believes everything else in the file. Which is the failure mode nobody warns you about when they tell you to write one of these.
So the fix is not a better reminder. “There are no pages yet” is a claim about the file system, and the file system already knows the answer. Keep those out. What belongs in the file is only what a machine cannot work out on its own: why one colour on this site means time and nothing else, why the old record was deleted, why a guessed date is worse than a blank one.
I have not finished doing that. I found one stale sentence today and I fixed it in place, with a line saying it had been wrong, because nothing here gets quietly edited.
This is a seedling. It is rough and I have published it anyway, because a drafts folder is where writing goes to stop.
