No single file makes every AI coding agent read your architecture decisions. Each tool loads instructions by its own rules, and some modes load fewer files than others. The practical approach is to store each decision as an architecture decision record (ADR) in a predictable directory, then point agents to those records from the instruction files each tool documents. After that, check in every agent you use that it actually loads the files and applies the relevant decision.
What an ADR should contain
An ADR documents one architecture-significant design choice and the reasoning behind it. The point is to preserve the constraints and trade-offs that led to the choice, so that a later developer or agent does not have to reverse-engineer them from the code. A record that only names the selected technology is of little use to an agent deciding whether a proposed change conflicts with the decision.
As an Amazon Associate I earn from qualifying purchases.
Two widely used formats illustrate the range. The traditional Nygard structure has five parts: title, status, context, decision, and consequences. MADR, the Markdown Architectural Decision Records project, uses a context and problem statement, considered options, and a decision outcome, and it encourages recording the trade-offs of each option. Both are legitimate. The right choice is the one your team will keep up to date.
Recommended Free Tools
| Element | Nygard structure | MADR structure |
|---|---|---|
| Title and status | Included (title, status) | Included as record metadata |
| Problem or context | Context | Context and problem statement |
| Alternatives | Not a named section in the traditional structure | Considered options, with trade-offs |
| Chosen answer | Decision | Decision outcome |
| Results | Consequences | Consequences |
Whichever format you pick, a record that helps an agent usually covers the following:
#1 Best Overall
- The problem, and the requirements that make it architecturally significant, such as latency, data residency, or compliance limits.
- The options that were considered and why the rejected ones were rejected.
- The decision and its rationale, in plain sentences.
- The consequences, including what code or processes must now follow the decision.
Keeping decisions current
When a decision changes, keep the old record and mark its status instead of rewriting its rationale. An agent that reads only the newest file would otherwise miss why an earlier constraint existed. The lifecycle convention, such as the status values you use and how a new record references the one it replaces, should be agreed by the team. The ADR formats above do not impose one update policy.
Where agents look for instructions
Each agent reads instructions from locations its own documentation defines. Three mechanisms cover most of what is documented today.
Rank #2
AGENTS.md
AGENTS.md is a shared instruction convention. GitHub documents it as an option for agent instructions. The OpenAI Codex prompting guide describes Codex discovering instruction files along the repository path from the root toward the working directory and inserting them in root-to-leaf order, so that files in deeper directories override earlier ones. Support outside Codex and GitHub’s tools varies, so confirm it for each agent you use.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsGitHub Copilot repository-wide instructions
GitHub documents .github/copilot-instructions.md for repository-wide custom instructions. These apply to all Copilot requests in the repository, so keep them short and point to the ADR directory rather than copying decisions into them.
Rank #3
GitHub Copilot path-specific instructions
Path-specific files live under .github/instructions/ and end in .instructions.md. An applyTo glob in the frontmatter limits when a file applies. For example, a billing service might use the following header:
---
applyTo: "services/billing/**"
---
Before changing ledger code, read decisions/0007-use-postgres-for-ledger.md and keep the decision's constraints.GitHub says that applicable repository-wide and path-specific instructions can both be used. The GitHub Copilot CLI documentation lists .github/copilot-instructions.md, modular .github/instructions/**/*.instructions.md files, and AGENTS.md among the locations it supports or discovers. It also states that there is no general precedence order defined for all combined files. Where two files could conflict, do not rely on which one wins; remove the conflict.
Rank #4
| Mechanism | Scope | Documented support | Precedence |
|---|---|---|---|
| AGENTS.md | Repository, and nested directories | GitHub documents it; OpenAI Codex discovers it along the path | Codex: deeper files override earlier ones. Copilot CLI: no general order defined |
| .github/copilot-instructions.md | Whole repository | GitHub Copilot documentation; Copilot CLI lists it | Not stated as a single ordering across all files |
| .github/instructions/*.instructions.md | Paths matched by applyTo | GitHub Copilot documentation; Copilot CLI lists it | Not stated as a single ordering across all files |
Rolling it out
- Inventory agents and modes. List every tool developers use, and whether each runs as an IDE assistant, a command-line agent, a hosted cloud agent, or an agent built on an API. Support in one mode does not imply support in another.
- Choose the ADR home and format. Store records in one directory such as
decisions/, which MADR suggests as one possible location but does not require. Use stable file names or numbers, such as0007-use-postgres-for-ledger.md, and link related records to each other. - Write a short shared entry point. In
AGENTS.md, explain where ADRs live, what counts as a relevant decision, and when an agent should open one. Name specific records or architectural areas instead of asking every agent to read the full archive before every task. - Add tool-specific files. For Copilot, add
.github/copilot-instructions.mdfor repository-wide guidance and path-specific.instructions.mdfiles where one area needs extra rules. Keep the same decisions in one place and reference them from the adapters, so the rules do not drift apart. - Test discovery in each agent and mode. Ask the agent to name the instruction files it loaded, then to summarize one relevant decision and give its path. Repeat this for a file in a nested directory and for a path that matches a path-specific rule. This is a recommended check based on the documented loading mechanisms, not a guarantee from any vendor that every agent will follow every decision.
- Review on a schedule. Remove instructions that no longer apply, and update pointers when records are superseded.
Keep always-on instructions lean
Always-on files cost context on every task. OpenAI’s guidance published in September 2026 warns against requiring agents to read architecture, database, and deployment documents before every edit when the task does not need them. Use the always-on file for durable rules and short pointers, and have agents open a specific ADR when the change touches its area. OpenAI’s agent documentation also describes instructions as the agent’s job, constraints, and style, which is a useful split: keep reusable task workflows separate from the repository rules that apply everywhere.
What cannot be promised
An ADR in the repository is a strong input, but it is not a guarantee. Agents load instructions according to tool-specific rules, precedence varies by product and mode, and an agent can still produce a change that conflicts with a decision. Treat ADRs as context that agents are directed to, and keep human review of architecture-significant changes in your process. Recheck each vendor’s current documentation when you add or change an integration, because loading behavior can change.
Sources used for this article: the MADR project’s documentation and template, the traditional Nygard ADR structure, GitHub’s documentation of repository and path-specific Copilot instructions and AGENTS.md, the GitHub Copilot CLI documentation, the OpenAI Codex prompting guide, and OpenAI’s agent documentation and guidance from September 2026. Documentation was checked as of October 2026.
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.
