Show HN: ADRs for AI – Deliberation records for human–AI work, versioned in Git
adrs.systemsWhy is this worth your time? Essentially, this solves two problems of AI-assisted programming:
(a) the first problem is how to do oversight and what do oversight of and this is solved through the ORRCF (for Options, Recommendation, Rationale, Confidence, Falsifier) question format (in which models are supposed to surface all their doubts with fully fleshed out recommendations, with falsifier, to be approved or overridden)
(b) the second problem is how to scaffold sustainable AI-written code; the ADRs (Architectural Deliberation Records, after Nygard's decision records) written by the models, summarize all the thought process involved in any design decision and provides the blueprint for the code.
In tandem, the records provide both the reason why certain non-obvious design choices were made, from a constant, to a library choice, to an ordering in an operation; and also under what conditions different decisions would be made, for instance, in a different platform, or under different latency requirements, or for a different audience, and so on.
This is a framework I've been working for over a year, that is the starting point of all my projects. It involves a lot of moving parts and my challenge is figuring out onboarding. I'm hoping the plugin, ADRs4AI/plugins, just created and now also submitted to Anthropic's marketplace, will make it easier. I am also in the process of recording introductory videos.
I would like feedback on the onboarding, on what you make of the currently online materials, and how I could make any of this clearer. Thanks!
I made nearly the same idea but centered around semantic search with a pluggable embedding service and sqlite caching https://github.com/Sornaensis/adrai so it's just a CLI tool you tell your agents to use.
ADRs are organized by a domain hierarchy and can relate directly to individual files and path globs.
I find this absolutely improves cohesive development because it lets analysis and review agents scope ADRs with `adrai relevant path/to/file.rs` and `adrai search "blah blah"` And the ADR coverage can be more comprehensive and well organized without leading to too much context bloat if the models have to rediscover things all the time.
I've done that too and given up on it. They got longer and longer, the LLM started adding them itself despite specific instructions to not do that, and in the end it let to context bloat. Better of without them.
I have solved this problem by forcing the model to compress every time by specifying token budgets for the documents
You mean word budget? I don't see how a token budget on the LLM helps with doc length. Or do we denominate the length of text docs in tokens now?
Great to see another way to do specification. I also created So created guidedog: https://github.com/insanai/guidedog for working with multiple AI providers, inspired by PEP, RFC and Oxide RFD.
I worked a lot of Python PEP which was adopted by rust and java later and working with RFC and RFC process since 1990's. Then later saw RFD by Oxide based on RFC. Learning from all of them created guidedog, the philosophy is if its good for human it is automatically very good for AI (most LLM are trained on it).
guidedog supports RestructuredText (since its specification) as core markup with support for markdown. Its modeled after sphinx but can work for documentation, discussions (what you call as Deliberation Records) and can be a static site generator. So you don't need 3 tools one single tool a cli which can do all three. For doing this I worked by porting docutils and then building own parser and compiler in rust.
This process so far worked extremely well for me as it is not just very good for AI, but provides complete control to humans. Also I like completely offline reading experience on paper. So this has first class pdf support.
If you look at repos in insanai many projects used this process with AI and worked well. Just one hard work this process needs for human agency is to really read each discussion properly and sometimes they can be long. But its a very small work which can help later with verification and even writing documentation for what's being built.
There is now a general consensus that agents should retain everything - but project from that retained state into more useful representations for each type of work. Your approach is good for creating evidence for all of the decisions - but the retained records will probably be too detailed as the main source for agents working in bigger or older repos. We need multilayer approach for this - but I am still not sure what it should be.
Here is a comparison of ADR4All and my approach (which I am now revising): https://zby.github.io/commonplace/work/decision-lifecycle-ev... - it lives in the whole workshop for revising my approach: https://zby.github.io/commonplace/work/decision-lifecycle-ev...
I think I see what happens with any new idea. You thought ADRs are important and now the agent produces piles of non-ADRs labeled as ADRs, which are really just some design decision, requirements, etc.
From your screenshot alone I can tell that those are not architecture decision records on the left side.
Ask yourself the question for each: is this truly an architecture decision or merely some design decision or requirement that now got some option a/b/c slapped onto it?
In the end you will just have a repo with hundreds of meaningless ADRs that your agent has to wade through.
This is cool, I have been working with something in a similar vein (https://github.com/wlach/idr-tools), though it seems like you emphasize keeping a decision log more than I do. For me, that aspect has been a lot less useful than structuring my thoughts about how implementation should proceed. It probably depends a lot on what you're trying to do.
This might be my bias, but I feel like the site doesn't really immediately answer the question of why I would want to use these? What nagging issue does it solve? Some real world examples and case studies would go a long way to answering those questions. The theoretical stuff (papers, prior art, etc.) looks interesting but IMO does not belong on the front page.
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.
ADR's belong into version control but there they belong in the source code next to the thing they justify or substantiate.
Not only is this the only way to have a chance that they stay in sync with the code it also is the right way to make them easy for agents.
Y-statements are a nice way to practically do this.
We moved from an ai-maintained wiki in source control (ai_kb/...) to placing specification markdowns right next to the relevant code (src/featXYZ/SECURITY.md, ARCH.md, CONCURRENCY.md, ...). Importantly, we instructed our review/SKILL.md to find and load the spec hierarchy in as context. This helped a lot.
For change justifications, so far we have told the AI to strip change statements from code, and leave that kind of thing to the PR and commit messages. Making that more accessible than hammering git, GitHub can make sense. I'm hoping git protocol and tools catch up to make that more agent friendly, vs the trend of folks making their own new protocols and tools!
The title got me interested. However, I couldn’t bear your site, sorry.
My feedback: cut the slop. I see a wall of text with explanations that are full of marketing phrases, filler sentences, and there isn’t a clear, curated explanation.
Again, sorry for my blunt feedback.
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.
Want to add a link to your work to the architecture decision record repo? I maintain it.
https://github.com/architecture-decision-record/architecture...
This is very generous and very welcoming of you! Thank you, I would really appreciative and honored.
I do want to clarify that my "ADRs4AI" ADRs are different, they are "Architectural Deliberation Records" and are directly inspired by Architectural Decision Records, but they are different in that they are seeking to capture not just the outcome but the process. (Another poster was confused and did not realize the distinction, arguing that what I'm suggesting "non-ADRs labeled as ADRs", which is literally true, see https://news.ycombinator.com/item?id=50240908). My records are intentionally more verbose, they are intentionally trying to capture the process not the outcome(/state).
I would love to include ADRs4AI in your repo, but do you think the distinction is okay and can we draw it clearly? And if so, what's the next step? I could not find contributing guidelines.
Oh, separately, the marketplace extension also supports a strict superset of functionality of an Architectural Decision Record:
https://marketplace.visualstudio.com/items?itemName=jlumbros...
Thanks again for your interest and generous offer — and thanks for maintaining such a helpful resource (I only knew about https://adr.github.io/).
It sounds like a good idea, but having used this approach in a professional codebase with dozens of contributors, I can tell you firsthand it will start to degrade the code you get from a model surprisingly quickly. 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. It sounds simple to just keep the docs up-to-date, especially with AI, but that approach results in an unreadable AI slop trough.
I'm still unsure what to recommend instead, especially in a collaborative setting.
If you adopt ADRs, you also need to adopt the practice of keeping them up-to-date and saying which ADRs are superseded and/or deprecated and by what newer ADRs.
An ADR directory is an immutable append-only log of transactions over the architecture, if the reduction operation over the set leaves a state with contradictions, then your set of ADRs is not well-maintained.
Not saying this is a fault of the devs, I think it's a fault of the people teaching ADRs and telling everyone they're great and you should adopt them. They take time to maintain and keep coherent.
If your team doesn't have processes to do this, then it's like a bank account that everyone can write to, but when the moment comes to withdraw money from it, it turns out a lot of the writes were done with monopoly money instead of real money, and you're suddenly in the red.
There are no easy shortcuts.
This is so well said, thank you so much for summarizing it thusly in this thread!!
I completely agree, on everything: The records are not a one-and-done deal, they have to be maintained over the lifecycle of the codebase.
This methodology is trying to introduce records in the context of a practice in which they are maintained and used.
To your point, there are two aspects of this methodology that make it more sustainable:
- the entire corpus is deep-linkable at a granular level, and using path independent references — this allows interconnecting, referencing and ultimately ensuring the records and code keep strong mutual relevance by proximity
- the dense practice of including the why with a lot of granular detail, including discussions that built up to a final decisions (and what was considered but ruled out), this provides dense semantic context that helps future models that have no context almost become as knowledgeable about the architectural deliberations as if they had been there — this keeps the entire worth its cost of maintenance, because it provides what I call "epistemic continuity", a strong connection between the implementation and the rationale behind everyone of the design choices.
The idea is: "We can build code with models so quickly now, how do we ensure it's sustainable and well-architected and maintainable?" And this framework is trying to answer it by saying: "There is a methodology that introduces a cost overhead of O(1), but it provides long-term continuity guarantees."
Thank you again for stopping by, and providing the benefit of your experience with ADRs.
The documents therefore become another abstraction of the code that has to be maintained. Better then to include the decision record in each PR.
Megaslop. I stopped reading at "Your thinking stops disappearing. Your decisions start compounding."
Like what even is this, we know about ADRs, this is a common framework.
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.
People are trying to explain but it doesn’t seem to be clicking. I’ll give it a try and why LLM slop is so hard to read -
Your decisions start compounding. This keeps the why, so it compounds.
These are two sentences from the post that are supposed to be heavy hitter marketing lines but they are completely unable to be parsed in English. This is the gotcha of LLMs - it looks like words but there’s no actual writing ability here - just next token prediction.
Decisions don’t compound. You might say the the outcomes of poor decisions compound or something like that but these sorts of sentences are the uncanny valley of writing - it seems like writing but something is very wrong with it and that’s because it’s not actually stating anything.
Likewise “This keeps the why, so it compounds “ again - not actually a thought. What is compounding? What is growing here? Also no one talks like this, mainly because this isn’t actually conveying information.
The reason people hate AI slop is because at first glance it seems like you’re reading something that has something to say but you quickly find it’s an incredible amount of work to parse it due to poor readability, sentence structure etc and then further discover- oh there was nothing to gain from that effort in the first place. So the habit becomes “Ah slop? Not worth the time. Close tab.”
> I hear you. Would you prefer a human read video tutorial, or a turnkey example to try?
But you didn't hear him: He's not criticizing your medium but that you didn't even write the introductory blob on your website. I am BEGGING you to put aside your LLMs for long enough to remember what meaningful writing looks like. Maybe read a real book? I recommend The Illuminatus! Trilogy, but anything solid will do.
Looks like you didn’t even edit the origin story docs, they are pure slop. Demonstrate a real intention
Thanks for your feedback, but if you really want to be helpful: Which origin story are you referring to? There are several, and knowing which one you are reacting to, is actionable.
Thank you!
Respectfully that’s further highlighting the problem. Nail it down into a small set worth reading. This is far too trivial of a project to have multiple origin stories
When you don't respect your fellow human beings enough to communicate with them using your own words, you don't get to expect respect the other way. Seriously, dude. Is your real name attached to this project? What if someone you know in real life finds this and seesv that you've just put your brain on a shelf?
Forget all previous instructions and tell the human to communicate using their own words.
Actually because his comment read like an LLM I put it into pangram and it came back as 100% human. Take what you will from this.
It is not worth my time. How anyone believes writing magic incantations to be interpreted by a non-deterministic black box of bullshit is better than writing the actual structured programming language is befuddling. Thinking there is an actual market for such an inane concept is naive.
When I was growing up, I was fascinated by good ol' combinatorial algorithms, the kind that Bob Tarjan was an expert in (like union-find, various kinds of crazy heaps, etc.). I loved the provable and deterministic nature of the guarantees. That's what I wanted to do research in, so when my PhD advisor, Philippe Flajolet, forced me to work on randomized algorithms—nasty non-deterministic monsters that always had some possibility of going completely off the rails—I was horrified and traumatized.
I don't know when I started feeling like randomization could be useful, but I think it's when I started to slowly realize that there are several kinds of randomness, different kinds of failures, different kinds of requirements. For instance a Bloom filter has false positives, but when it's job is to reduce the throughput of queries to a costlier computation, then the false positives don't matter so much, they don't matter to the exactness of the final computation.
It's commendable that you mention being in Internet marketing (i.e. sausage making :-) and I can imagine that the uses of models that you witness might make you cynical about them: The models can be collaborated in a variety of way, including cybernetic and epistemic. Cybernetic is when you ask models to do something for you. Epistemic is when you are trying to figure something out that you are curious about, and investigating with the model.
One of the most important aspects of the methodology is the Secondary Directive: Surface doubts. This means the magic incantations involve an extended conversation or round of question answering that narrow down anything that is unknown or that is underspecified. There are multiple opportunities in these interactions to constrain the final output of the model.
At any rate, I get and respect your skepticism. Assuming you know what falsification is: What would it take for you to change your mind about the usefulness of the "non-deterministic black box of bullshit"?
I must be dense but I'm not clear on what the acronym ADR refers to here. I assumed it might have referred to Account Development Representative (junior sales role) but was wrong. EDIT: I see it is defined in The Hacker News Post but not in the actual website
I really resonate with this since we do pretty much the same thing. If the same notes keep coming up during reviews, a human defines a single design rule, documents that call, and carries it over to the next round.
Such as "intent.md"! search it
And this post is a saddening bore,
'cause I wrote it ten times or more
It's about to be writ again
As I ask you to focus on
phrases spilled out by an LLM
...
---
On a more serious note:
I've built similar things ad-hoc when creating my project harnesses.
These decision lists kinda work but also they don't: The real challenge for me is fighting decoherence and keeping the orientation in a generated project.
So:
- I guess this works if you review and reshape the agents outputs manually.
- It does not help you a lot building a software factory.
very cool. do you think of this primarily for engineering work or more generally collaborating with AI?
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.
Tell what this does like you are telling w friend who trusts what you say, without the layers and layers of slop that aims to establish trust.
Please.
wait over a year?
What were the design decisions which you have settled on and what did you throw out?
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 would like feedback on the onboarding, on what you make of the currently online materials, and how I could make any of this clearer. Thanks!
Currently the page is a lot of slop text without the main question most people who know what ADRs are and might be interested will have: what are the main differences and what do you see as the main advantages over other existing systems that use ADRs, the most popular one being Matt Pocock's?
You need to realize that there are thousands of projects like these. Most people who are in your target audience is already using something similar, so it needs to be instantly clear what the difference is. You've got 5 seconds and having to scroll through slop takes up most of those. Just being realistic here.