ADRs4AI for AI Applications Teams: Capture Reasoning Before It Disappears

AIdataNewsGlobal — David Nakamura — editorial@aidatanews.com

When an AI assistant helps draft a decision, the durable asset is not only the final text. It is the path that explains why one option was chosen, what evidence mattered, and what future worker can reuse. ADRs4AI approaches that path by turning human-AI discussion into repository records, so judgments can compound instead of fading after each session.

Three surfaces where the record is used

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

Why the reasoning is the valuable residue

The central claim is that human-AI work produces its most valuable residue—the reasoning—and ordinary sessions lose it by default. The method stores that why, so later choices can build on earlier ones. In an application setting, that matters because a team often needs the reason behind a rule, not only the updated artifact.

A repository record, reproduced

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.

A ten-minute setup path

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

Create a copy of the template: gh repo create my-project --private --clone --template ADRs4AI/human-ai-collaboration-template-A and enter it with cd my-project.
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”
Recruit an agent: open claude, or your agent of choice, and offer the mission:

Hello — I have a mission for you. Read about it and tell me if you accept, or any pushback.
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, stated operationally

A practical cycle begins with capture. A messy dictated thought is stored as a seed. The assistant then separates that seed into ADR items that keep the original wording, the alternatives weighed, the explanation, and unanswered questions. Those questions can be found with a grep for ### QST:, from the editor extension, through the MCP server, or on the phone in your pocket. Because each item already includes options, recommendation, rationale, confidence, and falsifier, the person can answer by accepting or overriding. The practice converts deliberation into decisions that keep their reasons, easing cognitive load and preserving bandwidth.

No engineering background is required. The method grew from daily use by one person and an expanding set of AI collaborators, while the record remembers for veterans with many projects and beginners with their first.

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.

Common misconceptions

Do not mistake the record for transcript archival; it preserves decision structure rather than conversation volume.
Do not treat it as vector-database “memory”; the record is an explicit repository artifact.
Do not expect an orchestration platform; the surfaces help people review and commit decisions.
Do not infer persistent AI identity; the record persists, minds may change, and work can resume either way.

One map of the ecosystem

A single map named awesome-adrs4ai lists the ADRs4AI world: methodology and template, editors and clients, crew automation, projects practicing it, and learning and teaching. Entries are marked by kind and language.

Published papers

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.

Action recommendations

If your team needs a low-friction start, begin with the starter template and keep the first seed small.
If reviewers work mostly inside editors, prioritize the VS Code surface and Open VSX distribution.
If decision review happens away from a workstation, use the iOS client and App Store install path.
If agents must query the record, connect the MCP server before asking them to inspect options.
Before scaling a crew, first validate the personal loop: capture, partition, answer, commit.

The core premise

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.