How to Write the Best AGENTS.md File — Complete Guide
Write an AGENTS.md file that actually improves AI coding agent behavior — structure, what to include, what to omit, and real-world examples.
An AGENTS.md file exists to answer one question: what does an AI coding agent need to know that it can't figure out by reading the code? Get that scoping right and the file pays for itself on every single task; get it wrong and it's just dead weight in every context window.
Step 1: Start With Build, Test, and Run Commands
This is the highest-value section because it's the one thing an agent genuinely cannot infer reliably from the code alone — the same package.json might support multiple valid ways to run tests.
Being explicit about how to run a single test file, not just the whole suite, saves an agent from re-running an entire slow test suite after every small change.
Step 2: Document Non-Obvious Architectural Constraints
Skip anything visible from the folder structure. Focus on decisions a new engineer would need explained in onboarding.
These are the kinds of constraints that produce a genuinely wrong implementation if an agent guesses instead of being told — and they're exactly the details that don't show up from reading any single file.
Step 3: State Code Style Rules as Imperatives, Not Preferences
"Write good tests" or "keep code clean" produce inconsistent results because they're not falsifiable — an agent has no way to check if it complied. "Run npm run lint -- --fix before finishing" is a concrete, checkable instruction that gets followed reliably.
Step 4: Call Out What NOT to Touch
An explicit denylist prevents an agent from "helpfully" refactoring generated files or vendor code it doesn't have full context on.
Step 5: Add a Section for Testing Expectations
This is where a team's accumulated debugging lessons (like "don't mock the database, we got burned by it") belong — context that isn't derivable from the code but changes how an agent should validate its own work.
Step 6: Keep It Short and Prune Regularly
Because AGENTS.md is typically loaded into context on every single agent session, every line has a small but recurring token cost. A 600-line AGENTS.md that repeats information visible in package.json or the folder tree is actively worse than a 150-line one that only states what isn't otherwise discoverable.
A Minimal Template
Key Takeaways
The best AGENTS.md files contain only what an agent can't infer from reading the code itself — commands, non-obvious constraints, and checkable style rules — stated as concrete imperatives rather than vague preferences, kept under a few hundred lines since the file's token cost recurs on every single agent session.
