AGENTS.md
AGENTS.md is a plain Markdown file, usually kept at the root of a code repository, that tells AI coding agents how to work on that project: how to install, build and test it, the code style to follow, which folders to leave alone and anything else a new contributor would need to know. Think of it as a README written for agents instead of people.
Why it matters
A coding agent starts each session knowing nothing about your project. Without instructions it guesses, and the guesses are generic: the wrong test command, a formatting style your team doesn’t use, edits to files that are generated automatically. An AGENTS.md gives every session the same starting point, so you stop repeating the same instructions in prompts.
The name is a shared convention. Many coding agents, including Codex and Cursor, look for a file called AGENTS.md, so one file can serve a team where people use different tools. Some tools also read their own file, such as CLAUDE.md for Claude Code.
Writing a good one
- Commands first. Install, build, test and lint, exactly as they should be typed.
- Rules the code doesn’t show. “Never edit files in generated/” or “every API change needs a migration” are the kind of thing an agent can’t work out by reading.
- Short. The file goes into the agent’s context window every session, so a long one costs tokens and buries the rules that matter.
- Current. Review changes to it like code and update it when the project changes. A stale instruction is worse than none, because the agent will follow it.
Large repositories can have more than one, with a file in a subfolder adding rules for that part of the code.
How elvex relates
elvex publishes its own AGENTS.md: a setup guide written for agents, so a person can point their agent at it and have it work through connecting to elvex.