The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Keep AGENTS.md focused on guidance that applies to the repository as a whole. When a detailed convention already has a maintained home, point to that authoritative file and explain when it applies instead of copying its contents into a second place. Put path-specific rules in scoped instruction files when your coding tool supports them, and verify that the tool actually discovers the files you expect it to use.
What belongs in AGENTS.md?
AGENTS.md provides guidance to coding agents, such as repository conventions, project organization, and commands. Its scope follows the directory tree containing it, so instructions in a higher-level file can apply broadly while files in subdirectories can give more specific guidance.
As an Amazon Associate I earn from qualifying purchases.
Use an always-applicable file for decisions and workflows that matter across the repository and are not reliably inferable from the code. Keep short, critical instructions there when agents need them broadly; concision is a goal, not a reason to fragment useful guidance.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsWhen to reference a conventions document
If a complete, maintained set of conventions already lives elsewhere, make that file the canonical source and link to it from AGENTS.md. Say what the document governs and when the agent should consult it. For example:
# Repository guidance
- Follow the shared conventions in [docs/engineering-conventions.md](docs/engineering-conventions.md) for naming, error handling, and tests.
- For rules limited to a subtree, consult that subtree's scoped instructions.
- Before changing build or test workflows, use the commands listed below.The path above is illustrative; adapt it to the repository. Microsoft recommends reusing and referencing instruction files to avoid duplication, while its codebase guidance says project instructions are most useful for decisions agents cannot reliably infer from the code. A link can tell a human and an agent where the intended source is, but it does not guarantee that every tool automatically opens the linked file.
Choose a location by scope and tool behavior
Decide where each rule belongs by considering its reach, discoverability, maintenance, and portability:
Rank #2
| Location | Best fit | What to verify |
|---|---|---|
Root or broadly applicable AGENTS.md |
Guidance needed across the repository | Its directory-tree scope matches the intended reach. |
Canonical conventions document, referenced from AGENTS.md |
Detailed rules that already have a maintained home | The link resolves, the document’s authority and scope are clear, and the tool can access it when needed. |
| Scoped instruction file | Rules for a particular path, file type, language, or framework | The selected harness supports that pattern and applies it to the intended files. |
Support varies by coding tool. VS Code documents project-wide and targeted instruction approaches as well as harness-specific formats; do not assume that another agent interprets all of them the same way. GitHub’s Copilot CLI documentation, for example, says its built-in explore, task, and code-review subagents do not receive repository instruction files by default. That product-specific detail is a reason to check the target environment, not a general rule about all subagents.
Recommended Free Tools
How to reorganize duplicated rules
- Identify the canonical source. Find the maintained file containing the complete convention, and confirm it is the version contributors should follow.
- Keep broadly necessary guidance in place. Leave repository-wide instructions in
AGENTS.mdwhen they need to guide work throughout the tree. - Replace duplicated detail with a clear reference. Link to the canonical file and name its purpose and scope. Avoid a bare pointer that leaves readers guessing which rules matter.
- Move path-specific rules to scoped instructions where supported. Keep the scope narrow enough to match the files those rules govern.
- Resolve exceptions and precedence. Put exceptions in the scoped source or explicitly state which instruction takes priority, rather than keeping competing copies.
- Test the intended behavior. Use a small, realistic task in the target tool to check whether it discovers and follows the reference and scoped instructions.
What not to claim about file size
Official guidance supports focused, non-duplicative instructions; it does not establish an ideal word count, a maximum AGENTS.md size, or a measured token or performance benefit from linking instead of copying. Treat this as a maintainability and relevance choice. Keep essential instructions available where they are needed, and avoid promising numerical savings without measurements.
Quick Recap
Best Value
Rank #3
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.
