AGENTS.md is the right first step and the wrong place to stop. It gives an AI coding agent one global brief for an entire repository — but real codebases need context that is specific to the files in play and that updates as the code changes. AGENTS.md is static and repo-wide; the knowledge that prevents broken changes is local and living.
The AGENTS.md convention has spread fast for a good reason: agents, like new teammates, do their best work when they are briefed first. A root-level file that explains how the project is structured, what to run before committing, and which conventions to follow is a genuine upgrade over letting an agent guess from the code. The problem is what happens past the first screen of instructions.
What AGENTS.md is good at
- Always-true, repo-wide rules — the test command, the formatting convention, the "don’t commit to main" guardrail.
- Discovery — it is where an agent learns the project’s shape and where its deeper context lives.
- Portability — one plain-text file any agent can read, no integration required.
Keep it. Nothing here argues against AGENTS.md; it argues against expecting it to carry weight it was never designed for.
Where a single file runs out
1. It’s global, but knowledge is local
The invariant that matters when you touch src/billing/** is irrelevant — and just noise — when you touch src/ui/**. A single file either omits the billing invariant (and the agent breaks it) or includes every area’s caveats (and becomes an unreadable wall the agent skims past). The right unit is per-area context, delivered only for the files being changed.
2. It’s static, but code is living
AGENTS.md is written once and trusted forever, with no mechanism to notice when the code beneath it moves on. That is the exact setup for context drift: the file confidently describes a system that no longer exists, and the agent trusts it anyway.
3. It’s a brief, not a memory
A brief is what you tell someone on day one. A repo memory is what the team accumulates over years — the decisions, the rejected alternatives, the gotchas. You cannot fit that in a file an agent reads at the top of every session, nor should you try.
What "enough" looks like
Enough is code-anchored context: notes attached to the specific globs they govern, retrieved by path right before an edit, and flagged for review when the anchored code changes. Instead of one static brief, the agent gets the slice of knowledge that applies to exactly what it is about to touch:
driftless context get --files "src/billing/refunds/**"The difference is measurable as context coverage — how much of the codebase carries retrievable knowledge — rather than a single file that is either present or absent.
AGENTS.md as the front door
The two are not rivals. The best use of AGENTS.md is as the entry point to the deeper layer: keep the always-true rules inline, and point to the code-anchored context for everything area-specific. The agent reads the brief, discovers the context layer exists, and pulls from it before editing.
FAQ
Should I delete my AGENTS.md?
No. Keep it for repo-wide rules and as the discovery point for your context layer. Just stop trying to encode every area’s gotchas in it.
How is per-file context delivered without bloating the prompt?
By matching the files being changed against anchored topics and returning only the overlap — so the agent sees the billing invariant when it edits billing, and nothing about billing otherwise.
What goes in AGENTS.md vs. the context layer?
Always-true and global → AGENTS.md. Specific to an area and likely to change → the code-anchored context layer. For the why, see MCP vs. a context layer.
Driftless turns per-area knowledge into living, code-anchored context for humans and agents. See how it works.