Recommended Free Tools
An AI coding agent can ignore an architecture decision even when its ADR is committed in the repository: the file is not necessarily part of the agent’s working context. A reliable fix is to give the agent a short, actionable route to an ADR index, define which tasks trigger a lookup, and make decision status and conflicts explicit. That improves discoverability; it does not guarantee the agent will follow every decision.
Why does an AI agent miss a decision that is already documented?
Repository presence and task-time access are different things. An agent may work from the files and instructions it can see, without knowing that an ADR exists, where the index is, or which record governs the change. If the ADR’s status is unclear, it may also mistake a proposed or superseded record for current policy.
As an Amazon Associate I earn from qualifying purchases.
Not every miss is a context-window problem or a model defect. The ADR may not be linked from an entry point, the task may not trigger a search, the index may be stale, or the agent may find the right decision but lack the implementation skill to apply it. In a controlled study, Khatri reported implementation-skill failures among the reasons added context did not resolve failures on the tested tasks.
Free tools Windows power users keep installed
One-click scans. No signup required.
What should an ADR context auto-injection hook do?
Think of the hook as a retrieval workflow, not as a guarantee that the agent will obey. At minimum, it should route relevant tasks to the current decisions, give the agent a rule for handling conflicts, and make it possible to verify that retrieval happened.
#1 Best Overall
- Trigger: identify the kinds of changes that require an ADR lookup, such as changes to persistence, security, messaging, or public API behavior. Choose categories that match your repository.
- Retrieve: point the agent to an index and ask it to read matching accepted records and any records that supersede them.
- Apply: require the agent to name relevant constraints in its plan and surface a conflict rather than silently treating a new suggestion as approved policy.
- Verify: check that the retrieved records and their replacement links exist, then use automated checks for constraints that can be expressed deterministically.
How should you organize ADRs for selective retrieval?
Keep the records as the source of truth
Store the full decisions in version control, for example under docs/adr/, and maintain a compact index. Individual records can carry the context needed to evaluate them: the decision, rationale, alternatives, consequences, owner, date, and status. This is a practical structure, not a universal ADR standard.
Make lifecycle state visible. Distinguish accepted decisions from proposed, deprecated, or superseded records, and have a superseded record point to its replacement. Otherwise an agent may retrieve a historically important document and mistake it for current guidance.
Rank #2
Use a short entry point as a map
Put the retrieval rule in the repository’s agent-instruction mechanism, if the chosen platform provides one. Keep it concise: identify the ADR directory and index, list the task types that trigger a lookup, and say what to do when a requested change conflicts with an accepted decision. Link to detailed records rather than copying the whole decision history into an always-loaded instruction file.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
OpenAI’s 2025 engineering account describes using a short AGENTS.md as a map into deeper knowledge and gives roughly 100 lines as an example from its own practice. That is neither a universal size limit nor a tested threshold; the useful principle is progressive disclosure.
Rank #3
A repository-specific instruction could look like this:
Before changing persistence, security, messaging, or public API behavior:
1. Search docs/adr/README.md for decisions affecting the changed area.
2. Read matching accepted ADRs and any records that supersede them.
3. Name the relevant constraints in your plan.
4. If the requested change conflicts with an accepted ADR, explain the conflict
and ask for human review before implementing the conflicting change.
Do not treat a proposed ADR or an agent-generated suggestion as an accepted decision.Adjust the trigger list and paths to your project. The instruction is a routing rule; the index and ADRs remain the authoritative material.
Rank #4
Retrieve only what the task needs
Injecting every ADR into every task increases context load and can bury the relevant rule among historical decisions. Prefer searching the index and retrieving matching records. In a monorepo, scope the lookup to the affected service or path where the platform allows it, while still checking cross-cutting decisions that apply beyond that scope. Preserve each record’s status and supersession information when presenting it to the agent.
How do you adapt the hook to different coding agents?
Do not assume that one hook interface, filename, or lifecycle event works across products. The AgDR project documents separate integration locations for Claude Code, Codex, Cursor, GitHub Copilot, Windsurf, generic prompts, and Git pre-commit checks. That demonstrates the adapter pattern, not that every integration is vendor-supported or behaves equivalently.
Keep the ADR directory and index shared, then maintain a small adapter for each agent environment you actually use. Before relying on an adapter, verify its current product documentation and version: labels, supported instruction files, and hook APIs can change. A generic prompt or repository instruction may route retrieval without providing a true automatic hook; describe and test the mechanism you have rather than assuming equivalent behavior.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.How can you test retrieval and enforce decisions?
Test with a fresh session and a governed task
- Start a fresh agent session so the test does not depend on context from the person or agent that created the ADR.
- Give it a realistic task that changes an area covered by an accepted decision.
- Before asking it to implement, check whether it finds the relevant ADR, identifies its status, and notes any replacement record.
- Give it a conflicting request and confirm it surfaces the conflict for human review instead of silently proceeding as if the decision had changed.
- Check that the index links resolve and that superseded records point to their replacements.
These checks test whether the route works; they do not prove that every future task will retrieve or apply the right decision.
Move deterministic rules into automated checks
Use prose to explain rationale and guide judgment. For rules with an unambiguous implementation, add a linter, structural test, or CI check so violations can be detected independently of the agent’s recall. OpenAI describes using mechanical validation for documentation structure and architecture boundaries. A context hook can tell the agent why a boundary matters; a deterministic check can catch a violation that has a reliable machine-readable expression.
What does the evidence say about context files?
The available studies concern repository context files and agent performance, not an ADR-specific auto-injection hook. Their findings do not establish that injecting ADRs universally improves correctness or prevents architectural drift.
- Khatri, 2026: the study reports 288 evaluated runs across 17 real tasks in three repositories, using two agents and three context strategies with repeated runs. It found no measurable correctness change within its stated equivalence bounds. This is a result for that study’s design, not evidence that context never matters.
- Lulla et al., 2026: a study of 10 repositories and 124 pull requests reports an association between the presence of
AGENTS.mdand 28.64% lower median runtime and 16.58% lower output-token consumption, alongside comparable task-completion behavior. The source page contains placeholder DOI/ISBN metadata, so the publication status and full paper should be verified before treating this as strong general evidence.
Together, the findings support a measured conclusion: organized context may change how an agent works, but these results do not show that a particular ADR hook will make an agent comply. Evaluate retrieval and compliance in your own workflow, and keep enforceable boundaries out of prose alone.
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.
