Free tools Windows power users keep installed
One-click scans. No signup required.
Use AGENTS.md for actionable project guidance when your coding agent supports and discovers it; use README to explain the project and help people get started. They serve different readers, so a repository can—and often should—have both. The important check is whether your specific agent and session actually load the instruction file.
What each file is for
README: explain the project to people
A repository README is usually the first information visitors encounter. GitHub describes its typical purpose as explaining what a project does, why it is useful, how to get started, where to get help, and who maintains it. See GitHub’s README documentation.
That makes README the natural home for the human-facing overview and onboarding path: what the project is, prerequisites, basic setup, and where contributors or users can find help. It can also mention how to use an AI coding agent, but do not assume an agent will treat the README as its instruction source.
AGENTS.md: give a coding agent project context
AGENTS.md is a Markdown format for agent-focused project guidance. The AGENTS.md project suggests information such as a project overview, build and test commands, code style, testing practices, and security considerations. Microsoft’s VS Code documentation calls it “a cross-agent format for project guidance.” See the AGENTS.md project.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minute#1 Best Overall
Use it for concise, actionable details that help an agent make changes safely and consistently: how to run relevant checks, conventions to follow, architectural boundaries, and security-sensitive constraints. Keep general project explanation and user onboarding in README rather than duplicating them wholesale.
Which file should you choose?
| Question | README | AGENTS.md |
|---|---|---|
| Who is it primarily for? | People visiting, using, or contributing to the repository (GitHub Docs) | A coding agent that supports and discovers the file (AGENTS.md project) |
| What belongs there? | Project purpose, usefulness, getting started, help, and maintainers (GitHub Docs) | Project context, build/test commands, conventions, testing, and security guidance (AGENTS.md project) |
| Will every coding agent read it? | Not established; do not rely on README as an agent instruction mechanism | No. Support and discovery depend on the selected harness and session (VS Code documentation) |
| Is it the universal authority when instructions conflict? | No universal precedence is established | No; precedence and combination behavior vary by harness (OpenAI Codex and GitHub Copilot CLI documentation) |
In practice, the choice is usually not one file or the other. Keep README useful to people and put agent-specific operating rules in an instruction format the chosen harness documents. Link from one to the other if that helps readers, but avoid maintaining two competing copies of the same rules.
Check that your agent supports and loads the file
Do not infer support from the filename alone. Microsoft’s VS Code documentation identifies AGENTS.md as an option for OpenAI Codex and GitHub Copilot, while also listing formats such as .github/copilot-instructions.md and CLAUDE.md. Support varies with the selected harness and session type. VS Code’s Local agent can enable or disable AGENTS.md support, and nested-file discovery has a separate setting. Consult the current VS Code custom-instructions documentation for the configuration applicable to your environment.
- Identify the actual harness and session. Check the documentation for the agent or mode you will use; a product may offer more than one session type with different instruction behavior.
- Choose its documented instruction format. Use
AGENTS.mdif that harness supports it. Otherwise, use its native instruction file or a documented fallback mechanism, if available. - Check discovery settings and scope. Confirm whether root and nested instruction files are enabled and which directories the harness searches.
- Verify in a fresh session. Start a new session after changing settings or guidance and confirm the expected instructions are being applied before relying on them for consequential work.
How scope and precedence differ by harness
Codex: guidance accumulates toward the working directory
OpenAI documents Codex as reading AGENTS.md files before doing work. Applicable guidance is assembled from global scope and then project directories between the repository root and the current working directory, with closer-directory instructions appearing later in the combined prompt. Codex also documents AGENTS.override.md and configurable fallback names. These are Codex-specific rules, not a universal standard. See OpenAI’s Codex AGENTS.md guide.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Rank #3
This makes a root file appropriate for shared repository conventions and a nested file useful when a subdirectory has genuinely different instructions. Avoid creating narrower files merely to repeat the root guidance.
GitHub Copilot CLI: applicable files are combined
GitHub’s Copilot CLI documentation says applicable instruction files are combined and does not define a general precedence order among them. It advises avoiding conflicting instructions. Do not assume a later file automatically overrides an earlier one in this harness. See GitHub’s Copilot CLI instructions documentation.
Because combination behavior differs, phrase instructions so that they fit together. When directory-specific guidance is necessary, state its intended scope clearly and check the harness documentation rather than relying on an assumed override rule.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.A practical repository setup
Keep the root AGENTS.md operational
For a repository used with a compatible agent, make the root AGENTS.md a concise working guide. Useful items include:
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteBest Value
- Commands for setup, build, tests, and relevant checks.
- Code conventions and architectural constraints that apply across the repository.
- Important security requirements or sensitive areas an agent should treat carefully.
- A pointer to README for project purpose, onboarding, and other human-facing information.
Add nested guidance only for real differences
A nested instruction file can help when a subproject has its own commands, conventions, or constraints. Codex’s documented root-to-working-directory collection supports layered guidance; VS Code also describes targeted instructions as an option. Before adding nested files, confirm that the harness discovers them and that the instructions will not conflict with other applicable files.
Keep README focused on onboarding
Use README to introduce the project, explain how people can start, and point them to support and contribution information. If it contains a useful setup command that agents also need, you can refer to it from the agent guidance; keep the agent’s required operational rules explicit rather than expecting it to infer them from a human-oriented overview.
Quick Recap
Common mistakes to avoid
- Assuming every agent reads AGENTS.md. Support is harness-specific; check the relevant product documentation and session settings.
- Treating AGENTS.md as a universal override. Codex and Copilot CLI document different instruction-combination behavior, so precedence cannot be generalized.
- Putting everything in README because it is familiar. README’s documented purpose is repository communication to people, not a guaranteed agent instruction channel.
- Copying all README content into agent instructions. Keep guidance concise and task-relevant to reduce duplication and the chance that the two files drift.
- Relying on instructions you have not verified are loaded. A supported filename is not enough if discovery is disabled or the session does not search the relevant path.
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.
