A New AI Collaboration Paradigm: Version-Controlling Human and AI Decision Records with Git

When AI Becomes a Colleague, How Should Decision Records Be Made?

In the Show HN section of Hacker News, a project called "ADRs for AI" sparked a small-scale discussion. It proposes migrating the Architecture Decision Record (ADR) pattern to human-AI collaboration scenarios, version-controlling every AI interaction, reasoning process, and final decision in Git.

This idea seems simple, yet it touches on a core pain point in the current deployment of AI applications: when AI participates in decision-making, how do we trace "why it was done this way"?

What Is ADRs for AI?

ADR (Architecture Decision Record) is a lightweight documentation format used in software engineering to record architectural decisions, typically containing fields such as context, decision, and consequences. ADRs for AI extends this structure to human-AI collaboration scenarios.

The project author's core proposition is: each collaboration with AI produces a "Deliberation Record," including the prompt, the AI's reasoning process (if obtainable), the human's choices and corrections, and the final adopted solution. These records are committed to a Git repository like code, enjoying the history tracing and diff comparison capabilities that version control provides.

This essentially transforms AI from a "black-box tool" into an "auditable collaborator."

ADR (Architecture Decision Record) was first proposed by Michael Nygard in 2011. Its core idea is to record each important architectural decision as a short Markdown file containing fields such as title, status, context, decision, and consequences, and to include it in version control alongside the code. A typical ADR file usually does not exceed one page, with incrementing numbers, stored in the doc/adr directory. This lightweight format became popular because it solved two chronic problems of traditional architecture documentation: first, documentation becoming disconnected from code; second, decision context being lost over time. ADRs for AI borrows this structure but extends the recorded object from "architectural decisions" to "human-AI collaborative decision processes," thus requiring new content such as prompts, model versions, and AI reasoning summaries to be added to the original fields. This is in effect a scenario-specific adaptation of the ADR pattern.

Why Do AI Decisions Need Version Control?

The adoption of AI-assisted decision-making has far outpaced the follow-up of governance mechanisms. Development teams use Copilot to write code, ChatGPT for technology selection, and AI to generate architecture proposals, but these interactions are often scattered across chat logs, clipboards, and personal notes, unable to form organizational memory.

ADRs for AI attempts to solve three specific problems:

Traceability: When an AI-assisted decision runs into problems six months later, the team can return to the deliberation record from that time and see clearly what the AI suggested and why humans adopted or modified it.

Reproducibility: Git commit records make "which model version and which prompt version was used at the time" queryable, avoiding the confusion of "results being completely different after switching models."

Knowledge accumulation: New members can understand the team's decision logic through deliberation records, rather than only seeing the final code.

Reproducibility in the AI context is more complex than in traditional software. Reproducing traditional code only requires locking dependency versions and the runtime environment, whereas reproducing AI decisions also involves uncontrollable factors on the model provider's side: calling the same model API with the same prompt at different times may return different results due to silent model updates; temperature parameters, system prompts, and context window length all affect output. Therefore, "reproducibility" in deliberation records is not result reproduction in the strict sense, but rather "restorability of decision conditions"—that is, being able to see the model identifier, full prompt text, and key parameters used at the time, thereby judging the source of result differences. This distinction is important for setting reasonable audit expectations.

The Ingenuity and Limitations of Git as AI Collaboration Infrastructure

Using Git to carry AI deliberation records is a smart choice. Developers are already accustomed to Git workflows, and concepts like PR, commit, and blame naturally fit the tracing needs of "who made what decision and when." Moreover, Git's diff capability can be used to compare different versions of prompts or AI outputs, which is far more efficient than manually organizing documents.

But the limitations are also obvious. Git excels at managing text, whereas AI interactions may contain large amounts of unstructured content—multi-turn conversations, image inputs, tool-call chains. Stuffing these into Markdown files quickly becomes bloated. Additionally, how should the granularity of deliberation records be determined? Recording too finely slows down the workflow, while recording too coarsely loses audit value. Some users in the Hacker News comment section noted that this approach is feasible for personal projects, but scaling it to teams requires supporting template standards and automation tools.

Git's diff mechanism is very efficient for line-level changes in plain text, but when faced with multi-turn conversations and tool-call chains in AI interactions, the semantic readability of line-level diffs drops sharply. A feasible mitigation approach is to split deliberation records into "structured metadata" (model, parameters, timestamps in YAML/JSON format) and "unstructured body" (conversation summaries in Markdown format)—the former facilitating machine parsing and automated validation, the latter facilitating human reading. In addition, Git LFS (Large File Storage) can be used to store screenshots or log attachments, avoiding repository bloat. Although these engineering practices are simple, they are infrastructure details that must be considered before scaling to teams.

Implications for AI Engineering

The value of ADRs for AI lies not in whether it is mature itself, but in the direction it points to: AI collaboration needs engineering. When we discuss AI programming and AI-assisted decision-making, the focus is often on model capabilities, while overlooking that the collaboration process itself also needs tool support.

This project is still an early attempt, but the questions it raises are worth pondering for every developer introducing AI into a team: does your team have a mechanism that can clearly explain how a certain AI-assisted decision came about? If not, perhaps you can start with a Git repository and a simple record template.

One-line Summary

ADRs for AI introduces the architecture decision record pattern into human-AI collaboration, using Git to version-control the AI decision process.

Paragraph Summary

ADRs for AI is an early project discussed on Hacker News that migrates the Architecture Decision Record (ADR) pattern from software engineering to human-AI collaboration scenarios, generating a "Deliberation Record" for each AI interaction that includes prompts, reasoning processes, and human corrections, and committing it to a Git repository for version control. The solution targets three pain points in AI-assisted decision-making: traceability, reproducibility, and knowledge accumulation, leveraging Git's commit and diff capabilities to achieve decision tracing and prompt comparison. However, managing unstructured AI interaction content with Git has limitations such as difficulty in determining granularity and repository bloat, and team-wide adoption requires supporting template standards and automation tools. The project reflects the trend that AI collaboration needs engineering support.