An effective AGENTS.md tells an AI coding agent what it cannot reliably infer from the repository: project conventions, important business logic, known quirks, and dependencies. Make each instruction specific enough to guide an action, put it at the narrowest useful scope, and test that your chosen agent both loads it and follows it.
What should I put in an AGENTS.md file?
Include repository-specific facts and working rules that materially affect how an agent should change or validate the code. OpenAI recommends using AGENTS.md to help Codex operate more effectively across prompts, including by documenting conventions, business logic, known quirks, and dependencies. See OpenAI’s Codex best practices.
- Conventions: naming, formatting, or design choices that are important but not obvious from nearby code.
- Business rules: domain constraints or behavior the agent must preserve.
- Known quirks and dependencies: compatibility requirements, integration assumptions, or pitfalls that are easy to miss.
- Project-specific validation: the actual commands or checks maintainers expect, but only when verified to exist and apply in the repository.
Avoid generic advice that could apply to any project, unverified architecture claims, or long descriptions that do not change the agent’s work. The OpenAI guide to agent instructions recommends clear, smaller steps and explicit actions or outputs to reduce ambiguity.
How do I write effective AGENTS.md instructions?
Turn each preference into an observable instruction: identify the scope, say what the agent should do, and define the expected result or check. “Use clean architecture” is broad; “Keep database access in the repository layer” gives the agent a concrete constraint. Microsoft uses the latter kind of project convention in its VS Code custom-instructions guidance.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
- Name the target: say which files, module, language, or task the rule applies to.
- Specify the action: use a direct verb such as “keep,” “run,” “add,” or “avoid.”
- State the check: where useful, say how completion is verified, such as running a repository’s established test command.
For example, “For changes to the payment module, preserve the existing retry behavior and run the payment tests” is more testable than “Be careful with payments.” Use such examples only when they reflect your actual project and its real checks.
How do nested AGENTS.md files work?
Put broad conventions in a root-level file, then use nested files only for rules that genuinely apply to a smaller directory or task. This reduces irrelevant instructions on unrelated work and lets local guidance address details that do not belong in the repository-wide rules.
In the Codex behavior described by OpenAI’s AGENTS.md guidance, a file applies to the directory tree rooted where it lives. For a file being changed, applicable instructions must be followed; deeper files take precedence over broader files when instructions conflict, while direct system, developer, or user instructions take precedence over AGENTS.md. Codex implementation comments describe collecting files from the project root down the path to the working directory, without traversing above the project root. This is Codex-specific behavior, not a universal rule for every agent or configuration.
When rules apply only to a file pattern, module, or language, use the target harness’s narrower instruction mechanism where available. For example, VS Code documents .instructions.md files with applyTo patterns and descriptions, and Claude rules with paths. Check the harness’s current documentation before relying on a particular discovery or precedence rule.
Does AGENTS.md work with multiple AI coding agents?
It can be shared when the tools you use support the format, but the filename alone does not guarantee identical discovery, activation, or precedence. Microsoft’s documentation notes that behavior depends on the selected harness and describes harness-specific customization options. Consult each agent’s current documentation and test the setup you actually use.
If tools need separate native instruction files, keep their shared project requirements consistent and avoid contradictory copies. Review generated instruction files before adopting them: paths, commands, and conventions may be incomplete or inaccurate until checked against the repository.
Rank #4
How can I tell whether my coding agent is following AGENTS.md?
Check discovery and behavior separately. A harness showing an instruction file confirms it found the file; it does not prove that the agent followed its rules. VS Code’s custom-instructions documentation makes this distinction explicitly.
- Confirm the target harness recognizes the intended instruction file and scope.
- Start a fresh conversation when appropriate, so the test is not relying on prior context.
- Give the agent a small, representative task with one clear success criterion tied to a rule in the file.
- Inspect the response, changed files, and tool activity to see whether it used the expected constraint or check.
- If it fails, verify the file path, scope, and harness configuration; then make the instruction more direct and repeat the test.
For Codex-specific details, consult the current Codex AGENTS.md guide; for other tools, verify their own documented loading behavior. Product documentation and repository source can change, so confirm version- or configuration-sensitive details against the tool you are using.
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
