Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
AGENTS.md is a Markdown file that gives compatible AI coding agents project-specific instructions for working in a codebase. It can explain the repository’s structure, verified build and test commands, coding conventions, and areas that need extra care. It is a shared convention—not a guarantee that every agent will find or follow the file, and not a security control.
What does AGENTS.md mean?
AGENTS refers to software agents, including AI coding agents; .md means the file is written in ordinary Markdown. The filename is a convention recognized by some tools, not a special file type with a universal parser. A team typically commits it alongside the source code so its guidance can change with the project.
In practical terms, it is a concise project briefing for an agent: what the codebase contains, how to make and verify changes, and which boundaries to respect. It can also help a human contributor, but it does not replace user documentation or a contribution guide.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
The AGENTS.md site describes the format as an open, cross-tool convention. That does not mean every product supports it or interprets its instructions in the same way. A tool might load the file automatically, support it only in certain workflows, use it alongside its own format, or ignore it. Check the current documentation for the particular agent you use.
What belongs in an AGENTS.md?
Include information that changes how an agent should work in this repository—especially facts that are easy to miss or costly to get wrong. Useful sections often cover:
- Project map: what the repository does and where its applications, packages, tests, and generated files live.
- Setup and commands: the verified commands for installing dependencies, building, testing, linting, formatting, and type-checking.
- Architecture: module boundaries, where new features belong, APIs that should not be bypassed, and which files are the source of truth.
- Code conventions: project-specific naming, error handling, logging, dependency, and public API expectations.
- Testing expectations: relevant test locations, required checks, integration-test needs, and when fixtures or snapshots should change.
- Change boundaries: generated or sensitive areas, files that should not be edited manually, and changes that need additional review or approval.
- Workflow and gotchas: repository-specific contribution steps, local services, environment requirements, or known failure modes.
OpenAI’s Codex repository illustrates this kind of project-specific guidance with material on repository structure, Rust conventions, testing, commands, and sensitive areas: Codex’s AGENTS.md. Treat its contents as an example, not a template to copy unchanged into a different project.
What does a useful file look like?
There is no required JSON, YAML, or XML schema. A plain Markdown file with clear headings and concrete instructions is enough. For example:
Recommended Free Tools
# Project instructions
## Overview
This repository contains the web application and its API.
## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`
- Type-check: `npm run typecheck`
## Working rules
- Add or update tests when behavior changes.
- Do not edit generated files manually.
- Keep public API changes backward compatible.Those commands are illustrative, not commands to paste blindly. Use the scripts and package manager actually defined by the repository. For instance, check package.json, pyproject.toml, Cargo.toml, or the project’s documented setup before adding a command. A wrong command is worse than no command because it gives the agent false confidence about how to verify its work.
Make instructions observable and actionable. “Run the focused test for the changed package” is more useful when the file also identifies the test command or location. “Follow best practices” is too vague to resolve a repository-specific choice.
Where should AGENTS.md go?
Start with a root-level file when the guidance applies across the repository:
repository/
├── AGENTS.md
├── src/
├── tests/
└── ...In a monorepo, add nested files only when a part of the tree has genuinely different commands, architecture, or conventions:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →repository/
├── AGENTS.md
├── frontend/
│ └── AGENTS.md
├── backend/
│ └── AGENTS.md
└── infrastructure/
└── AGENTS.mdKeep repository-wide rules at the root and put narrower exceptions near the code they govern. Make scope clear: a nested file should add or refine guidance for its area, rather than repeat the entire root document. Otherwise contributors and agents can encounter contradictions, such as one file requiring npm while another package uses pnpm.
How do agents find and apply it?
There is no single discovery or precedence rule shared by every product. Some tools search the working directory and its parents; others assemble multiple applicable files, recognize additional filenames, or rely on product-specific configuration. The name alone does not make an agent read the file.
Codex as a documented example
Codex’s documented instruction model applies repository guidance to the directory containing an instruction file and its descendants. In conflicts, more deeply nested guidance takes precedence over broader repository guidance, while direct system, developer, or user instructions rank higher. The relevant Codex prompt instructions explain that model.
The Codex implementation also identifies AGENTS.md and AGENTS.override.md among its project-instruction filenames and describes assembling project documents along the path to the working directory. Those are Codex implementation details, not rules that apply to all AGENTS.md readers; consult the Codex discovery implementation for its current behavior.
Check the tool you actually use
For another agent, verify its supported filename, search locations, nesting behavior, and conflict rules in that vendor’s current documentation. If instructions seem to have no effect, confirm that the session is operating in the intended repository and directory, and ask the tool to identify which instruction files it loaded. Do not assume that a file outside the tool’s search path—or in a remote or generated workspace—will be discovered.
A useful mental model is “user or tool-level guidance, repository-wide guidance, narrower directory guidance, then the task at hand,” but this is only a conceptual aid. Each product defines its own precedence and may merge, override, or omit files differently.
How is AGENTS.md different from README.md and other instruction files?
| File or format | Typical audience | Typical purpose |
|---|---|---|
README.md |
People evaluating, installing, or using the project | Describe the project, basic setup, and usage. |
CONTRIBUTING.md |
Human contributors | Explain contribution and review workflows. |
AGENTS.md |
Compatible coding agents, and often contributors | Give practical, repository-scoped instructions for making and checking changes. |
CLAUDE.md |
Claude Code users | Provide guidance through Claude Code’s instruction-file convention. |
GEMINI.md |
Gemini CLI users | Provide guidance through Gemini CLI’s instruction-file convention. |
.cursor/rules/*.mdc |
Cursor users | Use Cursor’s rules system, which can express tool-specific and path-oriented behavior. |
.github/copilot-instructions.md |
GitHub Copilot users | Provide guidance through GitHub’s Copilot instruction mechanism. |
These files can complement one another. Keep general project facts in human-facing documentation where they belong, and put agent-specific operational guidance in AGENTS.md when the tools your team uses support it. Use native files for capabilities or instructions specific to one product. Do not assume a reference, import, or symlink is supported across tools; verify the behavior, and consider checkout and Windows portability before relying on symlinks.
How do you write and maintain one well?
- Start from actual repository facts. Inspect the existing scripts, package-manager lockfiles, test layout, and architecture documentation. Describe commands and boundaries that are true now.
- Prioritize repeated, consequential mistakes. Include the setup steps, project conventions, or verification checks that agents or contributors most need to know; link to deeper documentation instead of copying it wholesale.
- Separate shared rules from local exceptions. Keep stable repository-wide guidance at the root and specialized details in the relevant subdirectory, with scope stated plainly.
- Write verifiable instructions. Prefer a named command or directory and an expected check over broad requests such as “make it clean.”
- Review the file like code. Run the listed commands to confirm them, inspect the change, and update the instructions when scripts or architecture change. For example, use
git diff -- AGENTS.mdandgit status --shortbefore committing.
Keep the file concise enough that its important guidance is not buried. Very long instructions consume context and can become harder to maintain; the Codex implementation, for example, has a combined project-document size limit, but that is a Codex-specific implementation constraint rather than a limit of the Markdown convention. See the implementation for details.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesWhat should not go in AGENTS.md?
- Secrets or credentials: never put API keys, passwords, private tokens, or local secret values in a versioned instruction file.
- Unverified or stale commands: check commands against the project and update them when the workflow changes.
- Unrelated or overly broad rules: do not burden every directory with instructions that only apply to one package or that merely restate generic conventions.
- Large documentation copies: link to maintained architecture, security, or testing documents instead.
- Unsafe autonomy: do not instruct an agent to deploy to production, ignore security warnings, or make irreversible changes without authorization.
Most importantly, AGENTS.md is guidance, not enforcement. It cannot grant or revoke access, guarantee that an agent ran tests, block a risky command, or replace CI, branch protection, code review, secret scanning, sandboxing, or deployment approvals.
What can go wrong?
- The agent does not load the file: the product may not support it, may use a different name, or may not search the directory where it lives. Check the tool’s documentation and confirm the active workspace.
- Nested rules conflict: clarify each file’s scope and put real exceptions close to the affected code. Do not assume every product resolves conflicts the way Codex does.
- Commands have gone stale: verify them against current scripts and update the file during package-manager or build-system changes.
- Instructions encourage unrelated work: replace open-ended requests such as “refactor for cleanliness” with task boundaries that discourage unnecessary changes.
- Untrusted text looks like an instruction: repository files, dependencies, generated output, issues, and web pages can contain misleading directions. Do not let such content override higher-priority user or safety requirements; review proposed commands and changes.
- Tool-specific files disagree: maintain shared rules in one place where practical, and make any product-specific differences explicit instead of assuming all tools merge files identically.
Do you need an AGENTS.md?
It is most useful when a project has non-obvious setup or test commands, multiple packages with different conventions, architectural boundaries, or recurring mistakes that agents can avoid with clear guidance. It can also help a team using several compatible agents share a baseline instead of repeating the same project briefing.
For a tiny repository with obvious commands, it may add little beyond the README. It is also unlikely to help when the chosen agent does not support the format or when the file would duplicate documentation without adding agent-relevant details. If you do add one, keep it short, accurate, scoped, and backed by actual checks rather than treating it as a policy enforcement mechanism.
Quick Recap
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.
