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 →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
AI coding agents often miss an Architecture Decision Record (ADR) not because the record is absent, but because the task never directs the agent to find it, distinguish it from superseded decisions, and apply it. A reliable ADR context hook is therefore a small retrieval workflow: keep decisions in the repository, provide a concise map, trigger lookup for relevant changes, and verify the result.
Why an agent can miss a decision that is already in the repository
A committed ADR is available to an agent only if the agent can discover and read it during the task. Without a clear location, a lookup trigger, and a rule for determining which record is authoritative, the agent may plan from the code and the immediate request alone.
That gap has several possible causes: the index does not point to the decision, the task does not trigger retrieval, the record’s status is unclear, or the agent cannot implement the decision successfully. Khatri’s 2026 study of agent work reports implementation skill as one reason context did not resolve failures in its tested tasks. Adding more instructions will not by itself correct every implementation problem.
Design the hook as a retrieval workflow
Keep the ADRs as the source of truth and make the agent’s entry point a short map to them. The hook should tell the agent when to search, what to read, how to treat status and replacements, and what to do if a proposed change conflicts with an accepted decision.
#1 Best Overall
1. Keep complete records and a compact index
Store the full decision records in a version-controlled directory such as docs/adr/, alongside an index that links to them. Individual records can capture the decision, context, alternatives, constraints, consequences, owner, date, and status. This is a practical structure, not a universal ADR standard.
Make lifecycle information explicit. Mark records as accepted, proposed, deprecated, or superseded, and have a superseded record point to its replacement. Otherwise, a historical choice can look like current policy, while a proposed suggestion can be mistaken for an approved decision.
2. Use the agent instruction file as a map
In a repository with an agent instruction mechanism, use its entry point to identify the ADR directory and index, explain which task types require a lookup, and state how conflicts should be reported. OpenAI’s 2025 engineering description presents a short AGENTS.md as a map into deeper knowledge and gives roughly 100 lines as an example from its own practice—not as a tested threshold or universal limit.
Keep detailed rationale in the ADRs rather than copying the entire decision history into always-on instructions. This progressive-disclosure approach keeps the entry point actionable while allowing the agent to retrieve the detail relevant to the change.
3. Define a trigger and a conflict rule
Make lookup conditional on the kinds of work your repository governs. For example, a service might require an ADR search before changes to persistence, messaging, security, architecture boundaries, or public API behavior. Choose triggers that match actual decisions in that repository rather than adopting a generic list unchanged.
A usable instruction tells the agent to search the index for the affected area, read matching accepted records and their replacements, name the relevant constraints in its plan, and pause for human review if the intended change conflicts with an accepted decision. The pause matters: an agent’s suggested alternative should not silently become a new accepted decision.
Rank #4
4. Retrieve only the relevant scope
For a monorepo, scope the lookup to the affected service or path when the agent platform allows it. Include each retrieved record’s status, date, owner, and supersession link so the agent can assess authority and currency. Injecting every ADR for every task may add noise; retrieving too narrowly can omit a decision that crosses service boundaries.
Recommended Free Tools
Choose an implementation that fits the agent platform
Separate the shared decision records from platform-specific retrieval instructions. AgDR documents integration locations for several agent environments, generic prompts, and Git pre-commit checks. That demonstrates that adapters may differ; it does not establish that every listed integration is vendor-supported, equivalent, or stable across versions.
Best Value
Before implementing a product-specific hook, check that product’s current documentation and version. The portable part is the repository convention—index, lifecycle metadata, trigger conditions, and conflict behavior. The adapter is the mechanism that makes a given agent consult those materials.
| Approach | Context load | Scope and authority | Verification and upkeep |
|---|---|---|---|
| Inject every ADR for every task | High; includes unrelated history | Repository-wide; lifecycle still needs to be clear | Simple retrieval concept, but more context can mean more noise |
| Short entry point plus selective retrieval | Lower; retrieves matching records when triggered | Can be scoped by domain or path; status and replacement links must be maintained | Requires a maintained index and platform adapter |
| Prose instruction plus deterministic checks | Instruction can remain concise | Decision rationale is explained in records; enforceable rules are checked mechanically | Requires tests, lint rules, or CI checks for constraints that can be expressed unambiguously |
These are design trade-offs, not benchmarked results. The right balance depends on how often decisions cross repository boundaries, how much context a task needs, and the maintenance cost of indexes and adapters compared with the cost of agents missing current decisions.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Test whether retrieval works before trusting it
- Start a fresh agent session. Do not rely only on the session that created or edited the ADR; it may already have the decision in working context.
- Give it a task in a governed area. Ask it to identify the relevant accepted record and any conflict before proposing implementation changes.
- Check the retrieval path. Confirm the instruction points to the index, matching links resolve, and superseded records lead to their replacements.
- Check the decision handling. Verify that the agent names applicable constraints and surfaces a conflict for human review instead of silently treating a competing suggestion as approved.
- Automate deterministic constraints. Add linters, structural tests, or CI validation for boundaries that can be stated as rules. OpenAI describes using mechanical validation for documentation and architecture boundaries; these checks complement contextual guidance rather than replacing the rationale in an ADR.
What the available evidence does—and does not—show
The studies concern repository context files and agent performance under their own designs; neither directly tests an ADR-specific auto-injection hook. Their findings do not establish that injecting ADRs universally improves correctness or prevents architectural drift.
Free tools Windows power users keep installed
One-click scans. No signup required.
- Khatri’s 2026 controlled study reports 288 evaluated runs across 17 real tasks in three repositories, with two agents and three context strategies. It found no measurable correctness change within its stated equivalence bounds. That is a result for those tested conditions, not evidence that context never matters.
- Lulla and co-authors’ 2026 study reports an association across 10 repositories and 124 pull requests between the presence of
AGENTS.mdand 28.64% lower median runtime and 16.58% lower output-token consumption, with comparable task completion behavior. The source page contains placeholder DOI/ISBN metadata, so publication status and the full paper should be verified before treating the finding as strong general evidence.
The practical case for an ADR hook is narrower and more direct: a decision that is not discoverable when a relevant change is planned cannot reliably guide that change. Retrieval improves the route to the decision; it does not guarantee the agent will interpret or implement it correctly.
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.
