Free tools Windows power users keep installed
One-click scans. No signup required.
Use AGENTS.md for actionable project guidance when your chosen coding agent supports and discovers it; use README to explain the repository to people. They serve different audiences, so many projects should keep both—and verify the agent actually loads its instructions before relying on them.
What each file is for
README: explain the project to people
GitHub describes a repository README as typically the first information visitors see. It commonly explains what the project does, why it is useful, how to get started, where to get help, and who maintains it. See GitHub’s README documentation.
As an Amazon Associate I earn from qualifying purchases.
AGENTS.md: guide an AI coding agent
AGENTS.md is a Markdown file for agent-focused project context and instructions. The AGENTS.md project suggests material such as a project overview, build and test commands, coding style, testing expectations, and security notes: AGENTS.md. The aim is to give an agent concise, useful operating context—not to replace the human-oriented introduction.
Recommended Free Tools
Which file should guide your coding agent?
Put instructions in AGENTS.md if the specific agent harness you use supports that format and is configured to discover it. Do not assume every coding agent reads it, or that naming a file AGENTS.md automatically makes it active. Microsoft’s VS Code documentation calls it “a cross-agent format for project guidance,” while also making clear that supported formats and behavior depend on the selected harness and session type: Use custom instructions in VS Code.
#1 Best Overall
If the agent does not support AGENTS.md, use its documented native instruction format or a supported fallback. VS Code, for example, lists .github/copilot-instructions.md for Copilot and CLAUDE.md for Anthropic Claude alongside AGENTS.md. The correct choice is the format the selected agent actually loads.
How the files differ in practice
| Question | README | AGENTS.md |
|---|---|---|
| Primary reader | People visiting or using the repository | A coding agent working in the repository |
| Main job | Introduce the project and help people get started | Provide actionable project context and working rules |
| Useful contents | Purpose, why it is useful, setup, help, maintainers | Build and test commands, conventions, architecture constraints, testing and security guidance |
| Whether an agent will load it | Do not treat it as the agent’s instruction source unless that harness documents such behavior | Depends on harness support, discovery settings, and applicable scope |
How scope and instruction conflicts work
Instruction discovery and precedence are harness-specific. OpenAI’s Codex documentation says Codex reads AGENTS.md before doing work and describes guidance assembled from global scope and project directories from the repository root toward the current working directory. Closer directory guidance appears later in the combined prompt. Codex also documents AGENTS.override.md and configurable fallback names: Custom instructions with AGENTS.md.
GitHub Copilot CLI takes a different approach: its documentation says applicable instruction files are combined and specifies no general precedence order among them. GitHub advises avoiding conflicting instructions: Adding custom instructions for GitHub Copilot CLI. Therefore, do not assume that AGENTS.md always overrides README, or that one tool’s precedence rules apply to another.
At the repository level, write shared conventions and operating guidance once. Add narrower instruction files only when a directory or subproject genuinely needs different guidance and the chosen harness supports scoped discovery. VS Code also documents targeted instruction files as an option. Check the selected agent’s documentation for how it combines applicable files and resolves conflicts.
Rank #3
A practical setup for a repository
- Keep README focused on people. Explain the project, its purpose, how to install or start using it, where to find help, and who maintains it.
- Add a concise root
AGENTS.mdfor shared agent guidance. Include the relevant setup, build and test commands, code conventions, architecture constraints, and important security notes. - Use narrower instructions selectively. Add directory-specific guidance only where the subproject has distinct needs, and confirm the harness discovers files at that depth.
- Choose a native format when required. If your agent does not support
AGENTS.md, follow its documented instruction format or supported fallback instead. - Verify discovery in a fresh session. Check the agent’s documented behavior or ask it to report the applicable instructions it received before trusting the file to shape its work.
- Link the files when it helps readers. A brief link from the README to agent guidance—or from the guidance file to project onboarding—can connect them without duplicating their contents.
Bottom line
README is the human-facing project introduction; AGENTS.md is agent-facing guidance when the selected harness supports and discovers it. Keep both when the project has both audiences, and verify the harness’s discovery and conflict rules rather than assuming universal behavior.
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.
