iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Keep each architecture decision in its own Architecture Decision Record (ADR), then point your coding agents to those records through the instruction files each tool actually loads. No single file makes every agent read every decision. AGENTS.md is the closest thing to a shared convention, but support, discovery and precedence differ by tool, product and mode, so the working approach is to wire up each agent you use and confirm that it loads the files.
What an ADR should contain
An ADR documents one architecture-significant decision: a justified design choice that addresses a requirement with system-level consequences. One record should cover one decision, with the reasoning kept next to it. Two layouts are widely used, and both are legitimate. Pick the one your team will keep up.
| Element | Nygard-style record | MADR-style record |
|---|---|---|
| Core sections | Title, status, context, decision, consequences | Context and problem statement, considered options, decision outcome |
| Alternatives | Not part of the core structure | Options considered are listed explicitly |
| Trade-offs | Captured within context and consequences | Recorded per option; the project favors this practice |
| Suggested location | Not prescribed in the reference structure | decisions/ is suggested as one possible directory, not enforced |
Whichever layout you use, a record is most useful to a future developer or agent when it explains the constraints and reasoning, not just the chosen technology. Include:
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 →- The problem the decision solves and the quality requirements that drove it.
- The options considered and their trade-offs.
- The decision and the rationale behind it.
- The consequences, including what the team has accepted as a cost.
When a decision changes, keep the old record and mark its status rather than rewriting its rationale. The team should agree on the lifecycle convention, such as how a superseded record links to its replacement. The reference formats do not mandate one repository organization or update policy.
Where each agent reads instructions
Agents do not share one loading mechanism. The table below summarizes the documented locations as of early October 2026.
| Location | Tool or mode | Scope | Precedence or notes |
|---|---|---|---|
AGENTS.md |
Codex and other tools that implement the convention; GitHub documents it as an agent instruction option | Repository, with nested files possible | Codex discovers files along the repository path and inserts them root-to-leaf; later, deeper directories override earlier ones |
.github/copilot-instructions.md |
GitHub Copilot repository-wide custom instructions | Entire repository | Can be combined with path-specific files |
.github/instructions/*.instructions.md |
GitHub Copilot path-specific instructions | Files matched by an applyTo glob in frontmatter |
Applicable repository-wide and path-specific instructions can both be used |
.github/copilot-instructions.md, .github/instructions/**/*.instructions.md, AGENTS.md |
GitHub Copilot CLI discovered locations | Repository, with path-specific modular files | No general precedence order is defined for all combined files |
AGENTS.md
AGENTS.md works best for durable, cross-tool rules: where ADRs live, what makes a decision relevant, and when an agent should consult a record. Nested AGENTS.md files let a subdirectory add rules for its own area. Confirm support in each product you use, because the convention is recognized by some tools and not others.
Rank #2
GitHub Copilot repository-wide instructions
GitHub documents .github/copilot-instructions.md for repository-wide custom instructions. Keep it short. Name the ADR directory, state the rule for when to read it, and link to specific records rather than pasting their contents.
GitHub Copilot path-specific instructions
Files ending in .instructions.md under .github/instructions can be scoped with an applyTo glob in their frontmatter. A payments module, for example, could load a file that says which payments ADRs govern changes in src/payments/**. Use this when a decision applies only to one area, so the rule does not add context to unrelated tasks.
Rank #3
- Used Book in Good Condition
Copilot CLI
The Copilot CLI documentation lists the repository-wide file, the modular instruction files and AGENTS.md among its discovered locations. Because no general precedence order is defined for all combined files, avoid giving the same rule two different wordings in different files.
Reusable task workflows
Keep step-by-step task workflows separate from always-on rules where the agent supports that distinction. OpenAI’s agent documentation describes instructions as the agent’s job, constraints and style. OpenAI’s September 2026 Codex guidance warns against requiring agents to read architecture, database and deployment documents before every edit when the task does not need them. Put architecture pointers in always-on files and the full record text behind a pointer.
Rank #4
- Keep track of everything from attendance to test scores
- Spiral bound
- Measures 8-1/2" x 11"
Rolling out ADR-aware agents
- Inventory agents and execution modes. Record whether developers use IDE assistants, command-line agents, hosted cloud agents or agents built on an API. Support in one mode does not imply support in another.
- Choose the ADR home and format. Keep records in a predictable directory such as
decisions/, use stable file names or numbers, and link related decisions to one another. - Create the shared entry point. Write a short
AGENTS.mdthat explains where ADRs live, which changes count as architecturally significant, and when an agent should open a record. - Add tool-specific adapters. For Copilot, add
.github/copilot-instructions.mdand path-specific files where they help. KeepAGENTS.mdfor the tools that read it. Point every file to the same records so the rules do not diverge. - Test discovery. In each agent and mode, ask it to name the instruction files it loaded and to summarize one relevant decision with its path. Check nested directories, path-specific matching and conflicting wording.
- Review on a schedule. Remove stale pointers, update status fields when decisions change, and recheck vendor documentation whenever a tool or its instruction behavior changes.
Checking that agents actually loaded the rules
- Passes: the agent lists the expected file, cites the correct ADR path and applies the rule to a task inside the matching directory.
- Fails, file not listed: check the file name and location against the table above, and confirm the agent’s product and mode support that location.
- Fails, wrong path matched: review the
applyToglob in the path-specific file. - Fails, conflicting advice: consolidate the rule into one file and remove the duplicate wording.
A passing check shows that the agent loaded the instruction. It does not guarantee that the agent will follow the decision in every session, so keep code review as the enforcement step for architecture rules.
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 problemsQuick Recap
Best Value
- Broadman & Holman
- B & H 0AV Publishing Group
- Trading Paper
- 081407005744
- 5/1/2006
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.
