Blog / / 4 min read
Keep AGENTS.md true
An AGENTS.md that describes last month's codebase is worse than no AGENTS.md at all: the agent trusts it and builds on the wrong map. The habit that keeps the brief accurate, and how to make the agent do the updating for you.
The dangerous thing about a project brief is that agents believe it.
When AGENTS.md says blog posts live in src/content/posts with a pubDate field, the agent doesn’t verify that; it builds on it. That’s the point — the brief exists so the agent doesn’t have to rediscover the project every session. But it means the file has a failure mode that missing documentation doesn’t: confident wrongness. No brief, and the agent explores and guesses, visibly unsure. A stale brief, and it strides off in the wrong direction with full conviction, renames intact fields to match a schema that no longer exists, and puts new files where the old structure used to be.
If you customize your codebase and never touch the brief, you’re brewing exactly that.
The habit: same change, same diff
The fix is one sentence added to your prompts at the right moments:
“…and update AGENTS.md to match.”
Renamed a content collection? “Rename the posts collection to articles, update AGENTS.md to match.” Restructured pages, added a collection, swapped a dependency the brief mentions? Same suffix. The agent is the cheapest possible maintainer of this file: it just made the change, so it knows precisely what the brief should now say, and the update lands in the same diff where a reviewer can check both against each other.
This is the documentation habit that never worked for humans, finally working — because the writer is already in the room, already has the context, and doesn’t find documentation tedious.
The trigger doesn’t need to be a rule you memorize. A useful heuristic: if the change would surprise a new contributor reading the brief, the brief changes too. Renames, moves, new conventions, removed features — yes. A bugfix inside a function — no.
Review it like code, because it is
The brief’s diffs deserve the same thirty seconds of review as the code. Two things to watch:
Drift toward aspiration. Briefs rot in a specific direction: they start describing what someone intends instead of what exists. If the codebase is mid-migration, the brief should say so plainly (“legacy pages still use X; new pages use Y”) rather than pretending the migration is done. An agent reading an aspirational brief will produce aspirational code in a codebase that isn’t there yet.
Growth without pruning. Every update adds a line, nothing removes one, and eighteen months later the brief is a history document. Length is a cost: the brief competes for the agent’s attention with the actual task. When a section stops being load-bearing, delete it.
Every few weeks, a cheap audit closes the loop. Ask the agent itself: “Read AGENTS.md and verify each claim against the codebase; list anything that’s no longer true.” It’s a five-minute task for the agent and it catches the drift you’ve stopped seeing because you read past it every day.
Why this matters more on a codebase you bought
Every Lexington theme ships with an accurate AGENTS.md on day one; I extract it from the code, and it describes the theme as delivered. But the whole point of buying a theme is making it yours, and every customization you make is a small divergence from the brief you received.
Keep the brief in the loop and it stays what it was on day one: the reason your one-line prompts work. Let it drift and it quietly becomes the reason your agent keeps making the same strange mistake — it’s not hallucinating, it’s reading yesterday’s map.
The brief, the design skill, and the rules are a system, and this post is the maintenance manual for one corner of it. The other corners: why every theme ships with AGENTS.md, the design skill that keeps AI pages on-brand, and the four Cursor rules. The full method is Making Your Codebase AI-Ready.
/Michael Andreuzza