Show HN: ADRs for AI – Deliberation records for human–AI work, versioned in Git (adrs.systems)

53 pointsby lumbrosoa day ago30 comments

Why 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!

sornaensis an hour ago

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.

zby an hour ago

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...

vikrantrathore 2 hours ago

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.

jph an hour ago

Want to add a link to your work to the architecture decision record repo? I maintain it.

https://github.com/architecture-decision-record/architecture...

weinzierl 3 hours ago

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.

lmeyerov 34 minutes ago

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!

mzhaase 2 hours ago

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.

buster 3 hours ago

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.

wrlach 10 hours ago

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.

lumbroso 8 hours ago

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.

nickphx an hour ago

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.

diegof79 9 hours ago

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.

lumbroso 8 hours ago

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.

varyherb 6 hours ago

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.

azeirah 5 hours ago

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.

ethanj8011 10 hours ago

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.

lumbroso 9 hours ago

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.

CaveTech 8 hours ago

Looks like you didn’t even edit the origin story docs, they are pure slop. Demonstrate a real intention

lumbroso 8 hours ago

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!

CaveTech 8 hours ago

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

tad_tough_anne 8 hours ago

> 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.

IceDane 6 hours ago

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.

kensuh 6 hours ago

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

Garlef 3 hours ago

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.

dazzeloid 18 hours ago

very cool. do you think of this primarily for engineering work or more generally collaborating with AI?

lumbroso 16 hours ago

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.

ozozozd 6 hours ago

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.

4b11b4 10 hours ago

wait over a year?

What were the design decisions which you have settled on and what did you throw out?

lumbroso 9 hours ago

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!

deaux 5 hours ago

> 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.