AGENTS.md and CLAUDE.md: Writing Guardrails for AI Coding Agents

If you ask a modern LLM directly how to use AI well, you'll get a technically-correct, uselessly-anodyne response. Something like "use LLMs to accelerate and augment your work, not to bypass the understanding that makes you effective. When you ask a model to produce something, make sure you can evaluate its output critically."

Great. So "git gud" and "check everything." Technically correct, almost completely useless advice. Let's talk about the actual things that practitioners do now.

Since you're now appropriately paranoid about under-defining generative tasks (especially code), you might imagine that things like project-wide procedures and desired patterns would always be needed. Thankfully, the modern agent-based code systems have a nice way to do this, with an "AGENTS.md" file that lives in the root directory of a repo. AGENTS.md is basically the README file for agents, and is considered an open standard, always read by most commercial tools.

However, take a look at what Anthropic says about the CLAUDE.md file specifically (their version of this same concept, though they treat AGENTS.md the same way): "CLAUDE.md files are markdown files that give Claude persistent instructions for a project, your personal workflow, or your entire organization. You write them in plain text, and Claude reads them at the start of every session. Claude Code injects the CLAUDE.md with a system reminder noting the context 'may or may not be relevant to your tasks.' As a result, Claude will ignore the contents of your CLAUDE.md if it decides they are not relevant to its current task. The more information you have in the file that isn't universally applicable, the more likely Claude is to ignore your instructions."

See how they messed up just there? If the system actually decides at system start what is relevant, irrelevant parts could be explicitly removed from context at runtime in exchange for a cheaper and faster set of model runs, and a less burdened main LLM. It might seem like this would "even out," since another explicit LLM run would be necessary to decide what information would be "out" for the main run, but given that the file is injected into every turn of the LLM/agent system thereafter, putting the whole file in and just saying "meh, might ignore later" is fairly wasteful. But the incentive for Anthropic (and OpenAI, and others) is for the customer to use more tokens and make "more and more complete" use of their tools, so we probably won't see this sort of reasoning anytime soon.

So what goes into an agents.md file? Good AGENTS.md content may include:

• Project overview and architecture in a few sentences

• How to run the project locally if the AI will do that (build, test, lint commands)

• Key directories and what lives in them (if this is stable)

• Coding conventions and style rules not captured by linters

• Things the agent should never do (e.g., "do not modify migration files directly") — try to use positively-constructed language here if possible

• Any known landmines or non-obvious design decisions

The upshot of all of this is that the AGENTS.md file is where you can define what the agents can and cannot do, patterns you want them to follow, etc. And it's important to do this, in fact it can be very powerful. Adding the desired real structure of the project — how you want new API endpoints to be added, the fact that you don't necessarily want "fallbacks" unless explicitly asked for, etc. This is probably the best way to keep and enforce policies you want.