alt Hacker NewsShow HN: ADRs for AI – Deliberation records for human–AI work, versioned in Git
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!
Comments
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.
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.
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
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.
very cool. do you think of this primarily for engineering work or more generally collaborating with AI?
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?
> 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.
[flagged]
[dead]
[dead]
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.