AGENTS.md: The Repo Memory Every AI Coding Agent Needs

An AI coding agent can be powerful and still waste time if it does not know how your repository works. It may guess the package manager, miss a required check, follow the wrong pattern, or edit a generated file. AGENTS.md solves that problem by placing durable working instructions next to the code.

Think of it as the onboarding note you wish every new teammate would read before opening a pull request. It should help an agent act correctly without turning into a complete company handbook.

Write instructions that change behavior. The sentence “we value quality” is too vague. “Run the targeted test, type-check, and production build before handoff” is actionable. Mention unusual project details; skip facts the agent can discover instantly from standard files.

• The exact install, development, test, lint, type-check, and build commands
• A short map of important folders and the boundaries between systems
• Naming, formatting, component, data, and error-handling conventions
• Files that are generated, sensitive, fragile, or off limits
• The checks required before a task can be called complete

Start with a two-sentence description of the product and stack. Follow with commands, repository map, conventions, safety rules, and definition of done. Use short bullets and exact examples. If the file takes longer than a few minutes to scan, move detailed domain instructions closer to the relevant folder.

Nested instruction files are useful in large repositories. The root file can define rules for the whole project, while a file inside the mobile app or backend can describe local commands and conventions. That keeps guidance precise without flooding every task with irrelevant context.

• Copying the README instead of documenting how an agent should work
• Adding rules that are no longer enforced by the codebase
• Using vague language with no command, example, or expected result
• Forgetting to explain generated files and dangerous operations
• Letting the file grow without removing obsolete instructions

Update AGENTS.md when a command, architecture boundary, or team convention changes. When an agent makes the same mistake twice, ask whether the repository instructions could have prevented it. The best file grows from real failures, not imagined rules.

A concise, current AGENTS.md makes work faster, safer, and more consistent for every person using a coding agent on the repository. It is a small file with compounding returns.