How to Write an AGENTS.md That Actually Works
The file everyone adds and no one reads twice AGENTS.md has quietly become the standard way to tell a coding agent how to work inside your repository. Codex reads it, Cursor and Cline read their variants of it, and the agents.md convention is spreading fast. So teams add one — and then watch the agent ignore half of it. The problem is rarely that the agent can’t follow instructions. It’s that most AGENTS.md files are written like onboarding docs for a new human hire: a tour of the project, paragraphs of background, aspirational values. That is exactly the wrong shape for a file whose only job is to change what a model does on the next turn. ...