ItInsightsWorld SoftwareDevelopment: ADRs4AI Git Records for Human-AI Decisions

For teams that ship with both human judgment and AI assistance, the useful output of a session is not only the chosen answer. It is the trace of alternatives, rationale, and the moment a decision became binding. ADRs4AI keeps that trace in a repository, so later work can consult earlier choices without rebuilding the argument from chat history.

This guide focuses on the engineering path: how the three surfaces fit a development workflow, how a record is structured, how to start in about ten minutes, and what boundaries matter before a team adopts the method.

The three surfaces used by a delivery workflow

ADRs4AI offers three entry points.

• Starter template: a repository scaffold with ADR and seed templates, directives, an inbox protocol, and task-runner recipes; it can be adopted whole or by feature, and it works from the first seed.
• VS Code extension: open questions appear as tree views, malformed entries are flagged while text is typed, deep links connect views to files, and an MCP server lets agents query the record; the extension is also distributed through Open VSX.
• iOS client: a project’s open questions travel with the user: sign in, import a repo, review, and accept once; accepted answers arrive as commits, and the app is available on App Store.

A worked record from frontier-model-observatory

The sample comes from frontier-model-observatory’s own repository. It shows the division of labor: the machine raises and frames the question, GPT 5.6 Sol at Perplexity Computer supplies the recommendation, and Jérémie "Sonnet 4.5" Lumbroso answers through ADRs4AI mobile.

QST-HISTORICAL-TRUTH: How should corrections preserve what was previously believed?

• Status: answered
• Why asking: Conversation attribution needs "what was true or documented as of date X," while later research may correct earlier records.
• Need: Approve or revise the proposed temporal policy.

Options:

• A — Mutable present truth: Correct records in place; rely on Git history for prior states.
• B — Append-only assertions: Never change claims; append corrections and supersession edges.
• C — Bitemporal hybrid: Correct descriptive records when needed, while claims/events carry valid-time, observed-time, and explicit supersession; Git remains a third audit layer.

Recommendation: (by GPT 5.6 Sol at Perplexity Computer) C — Bitemporal hybrid.

Rationale: Git history records when repository bytes changed, not when a release became valid or when a provider made a statement. Explicit valid-time and observed-time support historical queries, while supersession edges preserve corrections without forcing every typo into an eternal domain event.

Confidence: High that Git history alone is insufficient; medium-high that two temporal axes cover the first release.

Falsifier: If real attribution cases require additional independent times, such as product-availability time distinct from announced and effective time, the temporal model must expand rather than overload either axis.

ANS: (by Jérémie "Sonnet 4.5" Lumbroso (via ADRs4AI mobile)) C — Bitemporal hybrid.

That single ruling closes the mechanic: the AI carries the reasoning, the person applies one judgment—accept, override, or another answer—and the why stays visible for anyone who reads the record later.

Comparing the correction options

Option	How corrections are stored	What the record preserves	Why C was recommended here
A — Mutable present truth	Correct records in place; rely on Git history for prior states.	Current truth and byte-level changes.	Git history alone is insufficient because it records when repository bytes changed, not when a release became valid or when a provider made a statement.
B — Append-only assertions	Never change claims; append corrections and supersession edges.	Every correction as an append.	It avoids silent overwriting, but may turn minor corrections, including typos, into lasting domain events.
C — Bitemporal hybrid	Correct descriptive records when needed, while claims/events carry valid-time, observed-time, and explicit supersession.	Historical queries, corrections, and Git as an audit layer.	Explicit valid-time and observed-time support historical queries, while supersession edges preserve corrections without forcing every typo into an eternal domain event.

A ten-minute engineering start

The commands below use the public template and then invite Claude, or your chosen agent, to take the mission.

1. # 1 · Your copy of the template
gh repo create my-project --private --clone \
--template ADRs4AI/human-ai-collaboration-template-A
cd my-project

2. # 2 · Open CLAUDE.md, fill in the top block (messy is fine),
# then stake the record before any work starts:
git add -A && git commit -m "chore: the record begins before the building does"

3. # 3 · Recruit — open your agent and offer the mission:
claude # or your agent of choice
# "Hello — I have a mission for you. Read about it and tell me if you accept, or any pushback."

   Then dump your thinking into a first seed — dictation is fine; your AI chunks it into ADRs that keep your actual words, the options, the reasoning, the open questions. Answer the first question it stakes. Every open question is one grep away, always:

   grep -rn "^### QST" docs/adr/

Running a crew—multiple seats, wake-on-brief, with the human no longer acting as the message bus—is optional; follow steps 7–9 of Get started.

The brief loop inside a SoftwareDevelopment flow

Capture first by dumping thoughts into a seed, even messy or dictated. The AI partitions them into ADRs that retain actual words, considered options, reasoning, and open questions. Questions are reachable by one grep for ### QST:, surfaced by the editor extension, the MCP server, or the phone in your pocket. Each arrives with options, recommendation, rationale, confidence, and falsifier, so an answer becomes accept or override.

In the extension’s Open Questions view for this same record, the panel shows a question, its options, an attributed recommendation, and the answer box: Question 16 of 75, that day.

The method does not require engineering experience. It grew from daily use by one person and an expanding set of AI collaborators, and the record remembers for veterans with many projects and beginners with their first.

Common misconceptions and boundaries

• It is not transcript archival.
• It is not vector-database "memory."
• It is not an orchestration platform.
• It does not claim that an AI has persistent identity; the record persists, minds may change, and work can resume either way.

FAQ

Does a team need a full engineering process before using ADRs4AI?

No. The text says it does not require engineering experience; the method grew from daily use by one person and an expanding set of AI collaborators. The record remembers for veterans with many projects and beginners with their first.

What does the human actually do?

The person applies one judgment: accept, override, or provide another answer. The AI carries the reasoning in the record.

How are open questions found?

By one grep for ### QST:, by the VS Code extension, by the MCP server, or through the iOS client.

What becomes the lasting artifact?

The decision, the options, the rationale, confidence, falsifier, and the final answer stay visible in the repository record.

Action suggestions

1. Start with a seed that captures current thinking, even if messy or dictated.
2. Commit the record before work starts.
3. Use the template named ADRs4AI/human-ai-collaboration-template-A as the first repository scaffold.
4. Let the agent frame the question with options, recommendation, rationale, confidence, and falsifier.
5. Answer through the editor or through ADRs4AI mobile when the question travels with you.
6. Keep the boundaries in mind: this is a decision record method, not transcript archival, vector-database memory, or orchestration.

One map of the ecosystem

The ADRs4AI world is listed on one page: methodology and template, editors and clients, crew automation, projects practicing it, and learning and teaching. Entries are marked by kind and language in awesome-adrs4ai, the curated map.

Published papers and citable references

• Cybernetic and Epistemic: A Missing Vocabulary for Trustworthy Agentic Delegation — accepted at the AAAI 2026 Fall Symposium on Trustworthy Agentic Systems (TAS 2026); arXiv:2610.00961.
• Deliberative Programming: A Versioned Deliberation Protocol for Human–AI Collectives — DOI 10.5281/zenodo.23300579.
• The methodology template is citable via concept DOI 10.5281/zenodo.23303469, always resolving to the latest archived release.

Core premise to keep in view

What the founding essay, What is ADRs4AI?, argues is not that the record makes an AI persistent or forces anyone to remember. It makes work resumable, and it lets thinking compound. The essay is written to be read cold; its authorship and review record are public because that is the method.