ADRs4AI: Versioned Deliberation Records for Human-AI Collaboration

Core Concept: Capturing the Reasoning Process

ADRs4AI addresses the problem of "evaporating" reasoning in human-AI collaboration by formalizing the deliberation process into versioned Architecture Decision Records (ADRs). While code is saved, the underlying logic, options considered, and trade-offs discussed with an AI model are typically lost. This framework mandates that these deliberations be captured in a structured, Git-versioned format, allowing future collaborators to understand the "why" behind specific implementation choices.

The ADRs4AI Workflow

The methodology centers on a simple loop: capturing a "seed" of intent, having the AI structure that intent into an ADR, and the human providing a final ruling. The process is designed to be integrated into standard development cycles:

  1. Seed: A user dumps their initial thoughts or requirements into a file.
  2. Structure: The AI processes this input, identifying open questions and proposing options with associated rationales, confidence levels, and potential falsifiers.
  3. Ruling: The human reviews the AI's recommendation and provides a final decision, which is then committed to the repository.

This workflow is supported by a VS Code extension that provides tree views of open questions and an iOS client that allows users to review and accept decisions on the go. The system uses a specific tag, ### QST:, to make open questions easily searchable via standard tools like grep.

Implementation and Tooling

The ecosystem provides several tools to lower the barrier to entry for adopting this practice:

  • Repository Template: A starter template containing ADR templates, directives, and inbox protocols.
  • VS Code Extension: Features diagnostics for malformed records and an MCP server, enabling AI agents to query the project's historical record.
  • iOS Client: A mobile interface for reviewing pending decisions and committing answers directly to the repository.

Community Feedback and Critiques

The reception of ADRs4AI on Hacker News highlighted both the potential utility of structured decision-making and practical concerns regarding implementation.

Some users expressed skepticism about the marketing-heavy presentation of the project, noting that the core concept of ADRs is already well-understood in software engineering. Others raised concerns about the risk of "doc rot" in AI-driven workflows:

"The agent will start to feel confused by the various conflicting 'guardrails' and 'constraints' the ADR is supposedly documenting. You will ask the agent why it did a particular contrived thing and it will cite various flawed or outdated assumptions. It's the same old problem of doc rot, but now the docs are blindly obeyed."

Conversely, proponents of the system noted that documenting design rules—such as an intent.md file—can be highly effective for maintaining consistency across AI-assisted development sessions. Users suggested that for the project to gain broader adoption, it needs to provide clearer, real-world case studies that demonstrate how it solves specific, nagging pain points beyond the theoretical benefits of documentation.

Sources