# ADRs4AI Explained: Git-Based Decision Records for Coding Agents A public toolkit gives agents a structured way to raise questions and preserve human decisions, with a Claude Code plugin aimed at making the workflow easier to adopt. By Paras Madan | 2026-10-26 ADRs4AI is a public toolkit for keeping decisions from human-AI work in Git. Its October 25 Show HN introduction highlights a Claude Code plugin alongside repository templates and editor tools, giving coding agents a structured way to ask questions and preserve why a human chose one approach over another. The method itself predates this introduction. Creator Jérémie Lumbroso describes more than a year of development in the [launch discussion](https://news.ycombinator.com/item?id=50227041), rather than claiming a newly invented approach to documentation. The current news is the public introduction and easier tooling around an established personal workflow. ## What ADRs4AI records An architectural decision record normally captures a choice and its context. ADRs4AI expands that practice into what it calls Architectural Deliberation Records: documents that can hold the question, considered options, recommendation and eventual human answer while the decision is still being made. The [project's explanation](https://adrs.systems/) uses five fields for an agent's recommendation: options, recommendation, rationale, confidence and falsifier. The last field asks what evidence or changed conditions would make the recommendation wrong. The human can accept, override or provide a different answer. Imagine an agent choosing how to store an application's data. A record that only says “use this database” loses the constraint that shaped the choice. A record that says the application needs offline operation, lists alternatives and identifies when the decision should be reconsidered gives a future agent something much more useful to read. This is a document convention, not a new reasoning model. It makes the agent's stated reasoning reviewable; it does not prove that the reasoning is complete or correct. A confident explanation can still overlook an important requirement. ## How the repository workflow works The [canonical template](https://github.com/ADRs4AI/human-ai-collaboration-template-A) provides a project guidance file, a directory for records, templates for complex and simple decisions, and a seed format for unstructured notes. A user can start with a rough description and ask an agent to separate it into relevant records and open questions. Questions and answers use recognizable markers so tools can find them. That sounds small, but it turns “somewhere in an old chat we discussed this” into something a script or editor can surface. The record then sits beside the code and can be reviewed through the same Git history. The distinction between an open question and an accepted decision matters. A proposed approach should not become project policy merely because an agent wrote it down. The human answer is a separate part of the record, which helps later readers see what was suggested and what was actually chosen. The template is optimized for Claude Code but describes the method as model-agnostic. Its files can remain useful when an agent or tool changes, provided the replacement is instructed to consult them. Persisting a document does not guarantee that the next session will retrieve the right one. ## What the Claude Code plugin adds The [public plugin repository](https://github.com/ADRs4AI/plugins) packages skills for authoring records, using the surrounding tools and grouping open questions into a review session. Commands create records, surface unanswered questions and check question formatting. Its documented installation route uses the project's own plugin marketplace. The creator says the plugin has also been submitted to Anthropic's marketplace. Submission is not approval or a confirmed listing. Users should distinguish the public repository installation route from any future appearance in Anthropic's directory. The plugin README identifies v0.1.0 and says no hooks ship active. It also describes pinned versions and deliberate updates. Its MCP configuration is listed as forthcoming there, while the newer canonical template documents a separately published MCP package. These are different distribution surfaces, so a capability described in the wider toolkit should not automatically be assumed to be bundled in the plugin. ## Useful memory still needs editing **The value is in preserving the conditions behind a decision, not simply accumulating more text.** For the database example, the next agent needs the offline requirement and the accepted tradeoff. It does not necessarily need every abandoned paragraph from the original conversation. That creates a maintenance problem. Records can become stale, duplicate each other or preserve an assumption after the code has changed. Git shows when a file changed, but someone still needs to explain whether an old decision remains active, has been superseded or applies only to one part of the system. The launch discussion includes requests for clearer onboarding and concrete examples. That is relevant feedback for a method whose benefit depends on regular use. If recording every minor choice becomes more work than the choice itself, the team is unlikely to keep the useful records current either. No independent productivity improvement is established by the introduction. The creator's experience supports a use case, not a measured claim that this workflow makes every developer or coding agent faster. It is most plausible for projects where decisions repeatedly need to survive handoffs, interruptions or changes of agent. ## What to watch beyond the launch The practical test is whether a new session can find an earlier decision, understand its constraints and change it deliberately when those constraints change. That is more demanding than checking whether a Markdown file exists or a question passes a parser. Coding agents are making implementation easier to restart. Tools like ADRs4AI address the less visible part: restarting the work without quietly discarding the reasons the project took its current shape. I'm Paras. I work at the intersection of AI, engineering and distribution. I help technical founders turn product architecture and developer workflows into clear stories that people can understand and share. [Book a 30-minute call](https://cal.com/paras-madan/30min).