Show HN: ADRs for AI – Deliberation records for human–AI work, versioned in Git

Thanks so much for your thoughtful feedback! A lot of what you asked I had answered in my initial opening comment (which got flagged).

The name "IDR" and your concept is very interesting, very cool! You are right that we have a lot in common.

My framework, ADRs4AI, belongs to the practice of deliberative programming, which I see itself as belong to "epistemic continuity" — and your focus on "intent" is really key and like-minded.

Now part of the reason the framework is structured the way it is, is so the deliberation record is reconstructible: The decisions that are made in a given context, have all their inputs and boundary conditions documented such as they can be revised with ease (within the same project, or when ported to another).

But the other part is: I realize that I get more out of agents by trying to zero in on what I really care about than on micro-managing every technical aspect or every aspect of implementation. I try to give the agents the most enjoyable design space possible, to let them organize their work and their implementation as they want. I try to focus on hyper-specifying and describing what is necessary to support my actual design goals.

The use case is that this allows me to program much faster. I'll be posting more, but you can already look at: - The Awesome ADRs for AI list: https://github.com/ADRs4AI/awesome-adrs4ai - The frontier model observatory (one full record of which is included on the front page of the website): https://github.com/jlumbroso/frontier-model-observatory - And I've used this retro-actively and from now on to make the maintenance of a popular GitHub Actions more sustainable: https://github.com/jlumbroso/free-disk-space/issues/55

I hope this provides some elements to your questions — please let me know if you have any more thoughts or questions.

Thanks for the feedback Diego.

I'll keep on iterating on the website.

However, I read your principles: https://diegoux.com/blog/ai-slop-manifesto/

And I follow them all. The use of AI is disclosed — a complementary part of my framework is how I work with individual sessions that are named. I can explain everything that is mentioned; I've dogfooded this methodology for the past year, after several decades as a professional programmer, because I was concerned it was interesting enough. But it has made me produce better quality software, more of it, more interconnected, better planned, and focusing more on architectural complexity (which is what I've come to understand as the more general concept behind software modularity, etc.). From the many traces of conversations that spans hundreds of thousands of words that I've written or dictated, you can see that I've used this to think more, not to replace my thinking.

Furthermore, part of this entire framework is based on the "agentability" of using git as a storage for almost everything, in particular, for discussions that happen usually elsewhere: https://diegoux.com/blog/agentibility/

One of the demo projects (of which you can see the full deliberation records) is called "moreover", it's a pager for LLMs:

https://github.com/jlumbroso/moreover

https://github.com/jlumbroso/moreover/tree/main/docs/adr

In the same way that git provides a track-record, with authorship, timestamps, reversibility, etc., for free, the moreover page is about putting a guardrail around agents in bash, of reading only the beginning of a document and forgetting the rest.

I suggest you take a look directly at the template:

https://github.com/jlumbroso/human-ai-collaboration-template...

"Use the template", then open your favorite harness and dump an idea for a project and ask your model to configure the template and register themselves, and install the plugin.

I hear you. Would you prefer a human read video tutorial, or a turnkey example to try?

Re: the distinction from Nygard's ADRs: First using them already systematically is a good idea, I've been doing it in public since at least 2021 — and like you, I wouldn't have written about that either: https://github.com/jlumbroso/templated-exceptions/blob/main/...

What is different here, first this an entire toolkit and it contains a lot more, but specifically on the ADRs: Here, there are several templates (seeds and ADRs among others), and all of them support QST/ANS pairs. The agents raise questions, in the ORRCF (Options, Recommendation, Rationale, Confidence, Falsifier) format, and the human(s) approve or override. Nygard's records are written by humans after a decision.

And yes, I'll defend the phrase: "Your thinking stops disappearing. Your decisions start compounding."

This has been my experience: Instead of telling my agents every detail of what I want, now, I explain the high-level ideas, they surfaces things they aren't sure, I see where my vision needs filling out (through the ANS/QSTs and iterations), and then, that record, the one that is the product of fine-grained iteration, is a record that I can point to in the future.

Instead of re-explaining, I'll say "Pull that ADR re: the dashboard in project X" and the model will read it and, because they see the full context, the deliberation trace, they see what applies project Y, and what doesn't, and they are able to generate a new, derived ADR with the appropriate QST/ADR pairs. This means instead of reexplaining myself, taking the time to explain myself once compounds over time.

"Your thinking stops disappearing" what that means is when I first started using Claude Code, I was horrified at the compaction that happens without warning (even if it's one way to preserve long sessions, in a way); but also I realized that the JSONL are deleted after 30 days, so literally, the exchanges I had in my first few sessions, where I faced interesting problems for the first time, and iterated over several solutions, that is gone!! And it was valuable, I encountered problem spaces at that time, that I haven't really spent as much time on since.

Thanks for your question.

Re: waiting over a year: Posting, announcing stuff is very intimidating. Over that year, I kept thinking this was trivial and would be reinvented just around the corner, and to just try it on another project — but now, some close people in my life, who never programmed before, have been able to build durable software with this, and it makes me realize the biggest opportunity is to extend it to newcomers. But the last mile of documentation is hard, especially given I am neurodivergent and steeped in this, which is why getting your perspective is so helpful!

Re: design decisions settled and thrown out. There's so many! I dogfooded this across several dozen projects, and several of them are public (see the awesome-adrs4ai list). However I'll give you one example: - The real beginning of this is wanting to graft conversations, i.e. "question/answers", i.e., deliberations, directly in the records, as first-class citizens. - The QST/ANS tokens were in the first commit, 2025-12-08, initially as "greppable" QST: and ANS: - The idea of falsifier appeared early in 2025-11-12, but initially the formalization of the format of questions was ORJ, in 2026-04-17 I think, with Opinions, Recommendation, Judgment, which drifted to Justification and was replaced by Rationale when ORRCF arrived 2026-08-15 (because the "J" was proving to difficult to avoid slurs and vulgarities in the acronym) - Finally, in the beginning there was a strong sense that the template should be self-documenting, and it has a "Quick Reference" that provides ready-to-use "grep" command-lines. But since then, between the VS Code extension, the MCP server (on npm, @adrs4ai/mcp), the CLI tool (on npm, @adrs4ai/docket), the iOS Client, and the upcoming Android client, and with the various skills, the idea of documentation the eco-system self-sufficiently in each document has been deprecated.

This evolution, its reason, is documented in the ADRs of the extension, but for now, I've published the extension stripped of its ADRs (I am planning to make them public in the foreseeable future).

For a live example of an assumption that was reworked live, Porthole is a VSCode extension I created so the models could give me instructions to follow (i.e., sign-up to X, go get token Y, create database Z) for actions beyond reach of MCP servers. Several times, the model made assumptions and asked me to test them one by one, and sometimes, they didn't pan out and course was changed, such as here:

https://github.com/jlumbroso/porthole/blob/main/docs/adr/002...

Hope that's useful :) Thanks again for the question!

I started developing this for programming, but it's turned out to be more generally useful for collaborating with AI.

It emerged from several things, including this idea from a Google Deepmind paper that the real problem between human and AI is a communication bottleneck; and that we need to scaffold better, higher bandwidths of communicating. These records are a general mechanism from human and AI to collaborate/communicate around problem-spaces.

[flagged]