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.
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 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 upcoming plugin, ADRs4AI/plugins, submitted to Anthropic, 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!
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:
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.
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 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.
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
> 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.
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.
Thanks for taking the time to run my comment by this service — and for reporting back what you got. (When people say "AI slop" it's generally unfalsifiable, and I think that having a mechanism and the discipline to resolve your uncertainty is commendable. Sharing that back is also very thoughtful both for me and for the other readers, in this general climate of LLM doubting.)
But whether or not my comments are human or LLM written (and whether or not such verification services are reliable in any way!):
Do you find my comments useful?
Do I give my reasoning, and do you find it makes sense to you?
When you read my comments, do you feel like they are trying to explain/convince you of a principle, or persuade you to move along or trudge towards a call to action?
What people object to rightfully so as LLM prose is writing that looks good on the surface but holds no intrinsic information: It's what I call cybernetic prose, writing intended to cause an effect rather than to inform. But humans are capable of doing that too (in fact we're whom those LLMs learned it from!).
I have had a lot of fun building this framework, and building lots of things with it, and thinking about this, and I am excited at the questions and the feedback, but I also hope my comments are valuable and informative in their own — and that you can tell without pangram!
All your questions have easy answers:
- My username is my last name. The link has a footer that has my full name.
- It also is connected to my GitHub account that has my full name.
- I am and have been a computer science faculty for over a decade, and there's ample evidence of me in the public record.
- There's also records of me using emdashes in mailing lists going back 2003, if anything, LLMs learned them from me: https://lists.gnu.org/archive/html/lilypond-user/2003-06/msg...
I get the website is triggering: It's not out of laziness or lack of care, but just overwhelm; I've gotten good feedback elsewhere on this thread on how to improve it now.
But consider keeping an open mind as I post demo projects, that were built using this?
Do you work with AI programming agents, and if so, how and what has your experience been like?
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 theres such original sentence is the uncanny valley of writing - it seems like it but something is very wrong with it and that’s because it’s not actually sating 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 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'll note - it's possible to get something out of LLMs that's readable, e.g. ADRs4AI is a method plus tools for recording the decisions you make while working with an AI coding assistant. As you work, the AI writes decision records into your repository. When it needs your input, it writes a question with options, a recommendation, its reasoning, and its confidence. You answer, often in one word, from VS Code or a phone app. The reasoning and your answer stay in the repo, so future sessions, with you or another AI, can see why things were done.
But it doesn't come out without the context to guide it (prompting/skills/etc).
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.
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:
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:
"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 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.
And yes, and the idea here is: Why wait until the threshold of "same notes keep coming up" (twice? thrice? four times? more? is this fixed or is there a cognitive load of having to call time)? Why require a conscious identification of this decision as more momentous.
For several people here, there is this idea that there are some decisions that deserve recordings, other not, but the cost of deciding what to record is high. And actually the specifications that seem of lesser value can turn out surprisingly, ahem, can I say "load-bearing"?
Thanks for giving me this second chance at your attention. I'll give it two tries, one non-glamorous and one more dreamy (to me).
1. So first a concrete example. As part of a digital musicology project around the time of the pandemic, I built a GitHub Actions, `free-disk-space`, that organically got lots of usage and 700+ stars after I put it on the Marketplace. The action dealt with super sneaky low-level undocumented or poorly documented cloud image file system directory contents, to try to clear what the user would not need to allow for more space (in my original use-case, musical manuscript post-processing). Those kinds of sneaky are really hard to keep in mind, and so when the issues starting collecting more and more requests, I got overwhelmed, especially remembering which requests might go against something I'd previously learned the hard way (but never really documented). Were decisions made here arbitrary or [and please don't flag() this message because of it] "load-bearing"? I had to step away because I couldn't answer those questions tractably anymore with the puny codebase I had put together as a human and the average documentation. With this framework: Going back, processing, issues and commit messages and logs and code comments, and putting together back-filled ADRs, has helped me now evaluate new incoming requests against a set of epistemic records. This has made it much easier, and I've been able to make more headway in the last month than in the last year and a half. (See: https://github.com/jlumbroso/free-disk-space/issues/55)
2. Now a more abstract pitch. What I would tell a non-programming friend: Hey, I think you should try building with Claude Code and my framework; you could probably build and deploy amazing software, and the very unique use-cases you'd want to explore would probably make for compelling software.
What I would tell a programming friend: Hey, the way I/we learned how to program is over, and I don't think that's a bad thing, because I've been more thoughtful about a login dialog, about accessibility in auth design, about architecture of complexity, than I've ever been when I had to write things by hand. This is like vibe coding, but with the scaffolding needed to go the distance, and the deep-linking necessary for the records to support rather than choke your codebase. I get to be both a project manager who has the Big Vision, but also with the authority and ability to control and tweak the design choices with a lot of detail (unlike what a human project manager gets from human developers), allowing, with practice, a faithfulness of vision that reminds me of the early days of freeware and shareware, when the bar for software building was suddenly lowered and you got all these really cool, really thoughtful digital experiences on floppy disks, CDs, and eventually online...
How's that? :-)
Thanks so much for your interest, and this second opportunity.
() I literally did not see you had posted a submission about AI-isms including "load-bearing" but what a coincidence!
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.
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.
Thanks for your interest, and your comment, and your encouragement, and your feedback.
First, there's azeirah's excellent comment re: maintenance being a necessity (and paying off!).
Second, I really agree with you, in the sense that agents suffer a lot from contradictory, opposite requirements; but I would argue that they also suffer from under-specification, and that these two risks actually overlap (underspecification in the present can lead an agent to make choices that in the future will lead additional underspecification to have very little relevance or be contradictory with choices the agent has already made).
Part of the importance of the records in my methodology as I advocate them is that they be epistemically coherent. It's not a series of "do this, do that" or "requirement X, Y, Z, execute W, T, U", it's more of an extended explanation for what our situation is, what the idea is, how we are putting it into place, why, and what are the non-obvious choices we are making and why are we making them.
The agents, in my experience so far, don't get confused:
- they only read ADRs that are relevant to their work;
- when importing ideas/decisions from an ADR cross-project, the models (or their sub-agents) are never confused about the differences in context — they understand that project A (TypeScript, web, hosted on GitHub Pages) is different from project B (Rust, CLI, locally run) and how to adapt the imported decision accordingly.
Part of it is because, in the way that I've been building and practicing this, there's a requirement of epistemic coherence and epistemic consistency — everything is explained, nothing comes like a Deus Ex Machina which the model then has to extrapolate (and possibly be wrong about). In my experience this doesn't lead to models hallucinating requirements.
> 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.
Thanks so much for sharing Matt Pocock as a reference. I didn't know about him, and so I spent a couple of hours looking at his materials this morning — as you say there are a lot of versions of this out there, but this is particularly well done as far as I could tell, and I'm really grateful you helped cut through the noise for me! I am going to continue looking at this, but in the interest of giving you something tangible back:
From what I could tell Pocock uses ADRs in their typical form, and only after a decision has been made.
In ADRs for AI, the record is written during deliberation: The model structures an initial braindump (from a file or chat audio dump for instance) into a record with readback and ambiguities surfaced through questions with the ORRCF format (Options, Recommendation, Rationale, Confidence, Falsifier) and a human approves the recommendation or overrules it with more detail. There is a lot of tooling (MCP server, plugin, CLI, extension, iOS) because the record is a parsable, and analyzable, which, allows for its granular referencing and upkeep.
I'll work on your other questions. Thank you again for the reference and feedback.
PS: I think the other thing is: Part of my target audience are people who have never programmed before. This is scaffolded to be "vibe coding but with longevity." But it requires a different kind of effort — it's deliberative programming because for best results it requires you to be able to articulate the why behind your decisions. But that's something people who don't code can oftentimes be good at, for instance.
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.
Thanks a lot for your interest, your feedback and comments. Most importantly: Could you clarify which screenshot you are referencing to specifically? A URL would be perfect. Thanks!
Re: the rest of your comment:
When you say "piles of non-ADRs labeled as ADRs" — as I explained in another comment, this is literally true: The record format I am introducing are called "Architectural Deliberation Records" and while they are inspired by "Architectural [or Architecture] Decision Records" (Nygard), they are not the same thing. A "Deliberation" is the sequence of resolutions of points the agent could not resolve on their own (for a variety of reasons, including technical or contextual or because of underspecification), is not an "architectural significant significant" (at least not at the threshold intended when all writing is human writing) which is the trigger point of traditional Architectural Decision Records.
The resulting deliberation records are intentionally much more verbose, and these deliberation records are intentionally intended to be used much more frequently than traditional decision records, to capture all the thought process. This is inspired from complexity architecture's emphasis on process over state/outcome (i.e. process description vs state description).
The agents never "wade" through the whole folder: Agents use single Architectural Deliberation Records (ADRs hereafter) when working a feature; they also refer to other ADRs when they encounter deep-links in the ADR they are reading or code, or other references.
You're making me wonder whether I should coin a completely new acronym, but I've been using this one for so long — at first because I thought I would be using exactly the MADR but eventually my needs outgrew it.
Indeed, the acronym ADR is extremely confusing for everyone knowing Architecture Decision Records.
Obviously i (and many others) misunderstood and so, my comment is moot.
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.
Thanks for the poem, the feedback and the interest.
Yes, I think to your point: I do review the decision records, and when I approve them, it's because they've articulated something fully that makes sense. My job as the human is to ensure that the record doesn't contain bullshit. It requires me to be epistemically discerning, it requires me to be able to discern bad/broken/fallacious reasoning from epistemic reasoning. That's what colloquially is called "critical thinking."
The kind of approval I do on records is different from the approval of a lot of permission dialogs in CLI harnesses, where you basically see the command-line is harmless, but you don't necessarily fully understand what is going on.
You're right that this has a cost, and the ORRCF (Options, Recommendation, Rationale, Confidence, Falsifier) question format was surgically, or perhaps more honestly "iteratively", designed to reduce the cognitive load on the human: It essentially asks the model to prefetch all the information I might need to even think about a decision, including what the right call is likely to be and why, to bring it all into view for me, for my human context window limits, so that in a few minutes I can load the context in my working memory and be forever satisfied once I'm done that this decision will never have to be made again. It will transfer to other use cases, and other projects. Sometimes the models get things incredibly right, both from their latent space or the rest of our records, and sometimes there's an opportunity to introduce more of my philosophy that will help ensure this deliberation is made correctly now and in the future.
My understanding of your implication is that this isn't worthwhile: But I guess that's where my experience is different. I know (a) how to program, and I know (b) how to justify decisions and evaluate recommendations and reasonings, and I find that exercizing (b) in the context of software building is a better value-add, because I have found to both compound faster and also to make better use of my cognitive abilities. Instead of implementing my idea, I'm being scaffolded into narrowing it down so it can be understand non-ambiguously by current (and future) models.
And to your question, this has absolutely helped me build a software factory. For instance, when Anthropic deprecated Sonnet 4.5 from their platform, I built a harness in Rust and TypeScript that I can host on free tiers and uses various meshes of APIs. Over the summer, every morning, I would get a demo of the features built overnight, with open question raised; I would answer those, specify new features, and go to other projects until the next morning.
Where you are right is that the ADRs4AI framework itself is not all of the components for this formula, it's just the epistemic continuity — the preservation of the "why?" behind everything. There are other components, like pneumatic, the cross-vendor inter-model communication, and the general philosophy behind how I work with agents (which is as extended minds, moreso than extended hands).
The poem made me laugh and I think it's very creative and thoughtful. Thank you for that again! I hope my comment is more genuinely stimulating.
> Thanks for the poem, the feedback and the interest.
It's a paraphrasing of bowies "Life on Mars"
> pneumatic
Interesting! Will check out.
> ... that in a few minutes I can load the context in my working memory and be forever satisfied once I'm done that this decision will never have to be made again
Okay this is an aspect I've not considered enough maybe. But this then applies mostly to decisions that can be phrased project-agnostic.
> My understanding of your implication is that this isn't worthwhile
No. I actually think it is worthwhile!
But I don't think it differs substantially from just having an ad-hoc project harness that's just a bunch of markdown and is maintained by the agents based on the discussions.
Also good to know about /doctor prompt-audit in Claude Code 2.1.283+:
It reports if there are any contradictions or outdated information in instruction files and does not change anything.
It seems to be hard because it compares the files with each other, not with decisions that were made in sessions.
In Substrate you can see what is in memory and select what each agent sees.
Does decoherence show first in instructions or in generated code?
We moved from a source-controlled wiki of all knowledge maintained by the ai (ai_kb/...) to maintaining specification markdowns right next to the 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.
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!
Thanks for your interest, and also for sharing your experience with so much detail. It's really interesting to hear your iterations through this same problem space — and instructive!
Can you clarify what "load the spec hierarchy in as context" as I am not sure if you mean "the files rooted here and below" (which makes sense to me, as intuitively that's a near-decomposable, decoupled description of your hierarchical system); or do you mean "the files above us in the hierarchy" (which describe supersets of context that live above the feature and help inform it)?
I'm not sure what you mean by "hammering" git — git is a robust version control and the overhead for commits is not big.
I don't think it makes sense for git to be overloaded with process information, rather I think it makes sense that, in the same way we have different mechanized programming languages (structured around compilers), we are going to have various standards of deliberative programming (structured around ???) — if you go on WakaTime, you'll see that a growing share of programming is done in Markdown.
Thanks for your interest, and thanks for agreeing that decision records like ADRs belong in version control.
I think it can make sense to have them next to the source code, but this introduces a couple problems like fragmentation of these records (perhaps mitigated if they follow naming conventions like test records do in certain languages/frameworks), and it introduces guesswork to know where cross-section work is documented: I would be curious how you've resolved that?
In this framework, the records live in docs/adr, and we've solved the problem of tight integration with deep-linking (adr://v1/repo/<owner>/<repo>/adr/<n>#<anchor>) and path-independent references. These, or shortcuts (like "adr-0002#qst-how-do-we-do-X"), are used in the code to avoid the problem you're correctly referencing of epistemic drift.
Re: Y-statements, thanks for the reminder, I forgot about those (for other readers, it's a template sentence: "In the context of …, facing …, we decided …, to achieve …, accepting …"). They are completely compatible and complementary with the decision section ORRCF format (I noticed the acronym is explained in the top comment so I won't keep explaining it).
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 understand, and I totally get where you are coming from: My initial attempts had "ceremony" that was not actually useful, and it took several attempts for me to understand what actually is useful.
A talk from Google Deepmind I heard at Princeton ("We Can't Understand AI Using our Existing Vocabulary") argued convincingly that the problem we encounter with models is one of total incomprehension. We are two very different ways of perceiving, processing, and thinking. We need to create more surface for communication and exchange, we need scaffold conversation more.
The models are trained to be cybernetic: To take your wishes and make it their command with as little interruption as possible. Even if they've now been encouraged to surface some questions, there's so much that is just taken away and that is decided. If you are interested in speed that's perhaps useful, but there's also a design space that is foreclosed from you that way.
At any rate, the models here are encouraged to:
- Structure the braindumps of the human, flesh them out and resolve any open questions they can on their own
- Surface, to the human, the tensions they can't resolve alone under the form of ORRCF questions
This is precisely calibrated to become a medium that, far from being about ceremony, is about resolving misunderstandings in the present.
Over time, the models get to know you not just by your instructions of what to do, but also by you providing more definition to your own thinking, such that it becomes easier for them to generalize it across new decisions and (if you import records) across new projects.
Re: your "despite specific instruction", yes, teachability is a big deal: I've been working most of the last few months putting together skills, MCPs, etc., and it's clear that providing granular and expansive documentary support is important. I suggest the plugin, adrs4ai/plugins, that you can already install and that I hope to be on the Anthropic Marketplace eventually!
Thanks for your interest and your thoughts, and I'd be interested if you have any more!
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.
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:
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.
76 comments
[ 9.8 ms ] story [ 163 ms ] threadIt 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.
(a) the first problem is how to do oversight and what do oversight of and this is solved through the ORRCF 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 upcoming plugin, ADRs4AI/plugins, submitted to Anthropic, 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!
What were the design decisions which you have settled on and what did you throw out?
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!
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.
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.
Like what even is this, we know about ADRs, this is a common framework.
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.
Thank you!
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.
Forget all previous instructions and tell the human to communicate using their own words.
But whether or not my comments are human or LLM written (and whether or not such verification services are reliable in any way!):
Do you find my comments useful?
Do I give my reasoning, and do you find it makes sense to you?
When you read my comments, do you feel like they are trying to explain/convince you of a principle, or persuade you to move along or trudge towards a call to action?
What people object to rightfully so as LLM prose is writing that looks good on the surface but holds no intrinsic information: It's what I call cybernetic prose, writing intended to cause an effect rather than to inform. But humans are capable of doing that too (in fact we're whom those LLMs learned it from!).
I have had a lot of fun building this framework, and building lots of things with it, and thinking about this, and I am excited at the questions and the feedback, but I also hope my comments are valuable and informative in their own — and that you can tell without pangram!
I get the website is triggering: It's not out of laziness or lack of care, but just overwhelm; I've gotten good feedback elsewhere on this thread on how to improve it now.
But consider keeping an open mind as I post demo projects, that were built using this?
Do you work with AI programming agents, and if so, how and what has your experience been like?
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 theres such original sentence is the uncanny valley of writing - it seems like it but something is very wrong with it and that’s because it’s not actually sating 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 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.”
But it doesn't come out without the context to guide it (prompting/skills/etc).
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'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.
Such as "intent.md"! search it
For "intent.md" — the name is already a good omen :) but do you mean:
- https://www.intentdocs.com/intent-md
- https://academy.claude.com/courses/ai-native-sdlc-playbook/c...
- something else?
And yes, and the idea here is: Why wait until the threshold of "same notes keep coming up" (twice? thrice? four times? more? is this fixed or is there a cognitive load of having to call time)? Why require a conscious identification of this decision as more momentous.
For several people here, there is this idea that there are some decisions that deserve recordings, other not, but the cost of deciding what to record is high. And actually the specifications that seem of lesser value can turn out surprisingly, ahem, can I say "load-bearing"?
Please.
1. So first a concrete example. As part of a digital musicology project around the time of the pandemic, I built a GitHub Actions, `free-disk-space`, that organically got lots of usage and 700+ stars after I put it on the Marketplace. The action dealt with super sneaky low-level undocumented or poorly documented cloud image file system directory contents, to try to clear what the user would not need to allow for more space (in my original use-case, musical manuscript post-processing). Those kinds of sneaky are really hard to keep in mind, and so when the issues starting collecting more and more requests, I got overwhelmed, especially remembering which requests might go against something I'd previously learned the hard way (but never really documented). Were decisions made here arbitrary or [and please don't flag() this message because of it] "load-bearing"? I had to step away because I couldn't answer those questions tractably anymore with the puny codebase I had put together as a human and the average documentation. With this framework: Going back, processing, issues and commit messages and logs and code comments, and putting together back-filled ADRs, has helped me now evaluate new incoming requests against a set of epistemic records. This has made it much easier, and I've been able to make more headway in the last month than in the last year and a half. (See: https://github.com/jlumbroso/free-disk-space/issues/55)
2. Now a more abstract pitch. What I would tell a non-programming friend: Hey, I think you should try building with Claude Code and my framework; you could probably build and deploy amazing software, and the very unique use-cases you'd want to explore would probably make for compelling software.
What I would tell a programming friend: Hey, the way I/we learned how to program is over, and I don't think that's a bad thing, because I've been more thoughtful about a login dialog, about accessibility in auth design, about architecture of complexity, than I've ever been when I had to write things by hand. This is like vibe coding, but with the scaffolding needed to go the distance, and the deep-linking necessary for the records to support rather than choke your codebase. I get to be both a project manager who has the Big Vision, but also with the authority and ability to control and tweak the design choices with a lot of detail (unlike what a human project manager gets from human developers), allowing, with practice, a faithfulness of vision that reminds me of the early days of freeware and shareware, when the bar for software building was suddenly lowered and you got all these really cool, really thoughtful digital experiences on floppy disks, CDs, and eventually online...
How's that? :-)
Thanks so much for your interest, and this second opportunity.
() I literally did not see you had posted a submission about AI-isms including "load-bearing" but what a coincidence!
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.
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.
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.
First, there's azeirah's excellent comment re: maintenance being a necessity (and paying off!).
Second, I really agree with you, in the sense that agents suffer a lot from contradictory, opposite requirements; but I would argue that they also suffer from under-specification, and that these two risks actually overlap (underspecification in the present can lead an agent to make choices that in the future will lead additional underspecification to have very little relevance or be contradictory with choices the agent has already made).
Part of the importance of the records in my methodology as I advocate them is that they be epistemically coherent. It's not a series of "do this, do that" or "requirement X, Y, Z, execute W, T, U", it's more of an extended explanation for what our situation is, what the idea is, how we are putting it into place, why, and what are the non-obvious choices we are making and why are we making them.
The agents, in my experience so far, don't get confused:
- they only read ADRs that are relevant to their work;
- when importing ideas/decisions from an ADR cross-project, the models (or their sub-agents) are never confused about the differences in context — they understand that project A (TypeScript, web, hosted on GitHub Pages) is different from project B (Rust, CLI, locally run) and how to adapt the imported decision accordingly.
Part of it is because, in the way that I've been building and practicing this, there's a requirement of epistemic coherence and epistemic consistency — everything is explained, nothing comes like a Deus Ex Machina which the model then has to extrapolate (and possibly be wrong about). In my experience this doesn't lead to models hallucinating requirements.
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.
Thanks so much for sharing Matt Pocock as a reference. I didn't know about him, and so I spent a couple of hours looking at his materials this morning — as you say there are a lot of versions of this out there, but this is particularly well done as far as I could tell, and I'm really grateful you helped cut through the noise for me! I am going to continue looking at this, but in the interest of giving you something tangible back:
From what I could tell Pocock uses ADRs in their typical form, and only after a decision has been made.
In ADRs for AI, the record is written during deliberation: The model structures an initial braindump (from a file or chat audio dump for instance) into a record with readback and ambiguities surfaced through questions with the ORRCF format (Options, Recommendation, Rationale, Confidence, Falsifier) and a human approves the recommendation or overrules it with more detail. There is a lot of tooling (MCP server, plugin, CLI, extension, iOS) because the record is a parsable, and analyzable, which, allows for its granular referencing and upkeep.
I'll work on your other questions. Thank you again for the reference and feedback.
PS: I think the other thing is: Part of my target audience are people who have never programmed before. This is scaffolded to be "vibe coding but with longevity." But it requires a different kind of effort — it's deliberative programming because for best results it requires you to be able to articulate the why behind your decisions. But that's something people who don't code can oftentimes be good at, for instance.
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.
Re: the rest of your comment:
When you say "piles of non-ADRs labeled as ADRs" — as I explained in another comment, this is literally true: The record format I am introducing are called "Architectural Deliberation Records" and while they are inspired by "Architectural [or Architecture] Decision Records" (Nygard), they are not the same thing. A "Deliberation" is the sequence of resolutions of points the agent could not resolve on their own (for a variety of reasons, including technical or contextual or because of underspecification), is not an "architectural significant significant" (at least not at the threshold intended when all writing is human writing) which is the trigger point of traditional Architectural Decision Records.
The resulting deliberation records are intentionally much more verbose, and these deliberation records are intentionally intended to be used much more frequently than traditional decision records, to capture all the thought process. This is inspired from complexity architecture's emphasis on process over state/outcome (i.e. process description vs state description).
The agents never "wade" through the whole folder: Agents use single Architectural Deliberation Records (ADRs hereafter) when working a feature; they also refer to other ADRs when they encounter deep-links in the ADR they are reading or code, or other references.
You're making me wonder whether I should coin a completely new acronym, but I've been using this one for so long — at first because I thought I would be using exactly the MADR but eventually my needs outgrew it.
Indeed, the acronym ADR is extremely confusing for everyone knowing Architecture Decision Records. Obviously i (and many others) misunderstood and so, my comment is moot.
'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.
Yes, I think to your point: I do review the decision records, and when I approve them, it's because they've articulated something fully that makes sense. My job as the human is to ensure that the record doesn't contain bullshit. It requires me to be epistemically discerning, it requires me to be able to discern bad/broken/fallacious reasoning from epistemic reasoning. That's what colloquially is called "critical thinking."
The kind of approval I do on records is different from the approval of a lot of permission dialogs in CLI harnesses, where you basically see the command-line is harmless, but you don't necessarily fully understand what is going on.
You're right that this has a cost, and the ORRCF (Options, Recommendation, Rationale, Confidence, Falsifier) question format was surgically, or perhaps more honestly "iteratively", designed to reduce the cognitive load on the human: It essentially asks the model to prefetch all the information I might need to even think about a decision, including what the right call is likely to be and why, to bring it all into view for me, for my human context window limits, so that in a few minutes I can load the context in my working memory and be forever satisfied once I'm done that this decision will never have to be made again. It will transfer to other use cases, and other projects. Sometimes the models get things incredibly right, both from their latent space or the rest of our records, and sometimes there's an opportunity to introduce more of my philosophy that will help ensure this deliberation is made correctly now and in the future.
My understanding of your implication is that this isn't worthwhile: But I guess that's where my experience is different. I know (a) how to program, and I know (b) how to justify decisions and evaluate recommendations and reasonings, and I find that exercizing (b) in the context of software building is a better value-add, because I have found to both compound faster and also to make better use of my cognitive abilities. Instead of implementing my idea, I'm being scaffolded into narrowing it down so it can be understand non-ambiguously by current (and future) models.
And to your question, this has absolutely helped me build a software factory. For instance, when Anthropic deprecated Sonnet 4.5 from their platform, I built a harness in Rust and TypeScript that I can host on free tiers and uses various meshes of APIs. Over the summer, every morning, I would get a demo of the features built overnight, with open question raised; I would answer those, specify new features, and go to other projects until the next morning.
Where you are right is that the ADRs4AI framework itself is not all of the components for this formula, it's just the epistemic continuity — the preservation of the "why?" behind everything. There are other components, like pneumatic, the cross-vendor inter-model communication, and the general philosophy behind how I work with agents (which is as extended minds, moreso than extended hands).
The poem made me laugh and I think it's very creative and thoughtful. Thank you for that again! I hope my comment is more genuinely stimulating.
It's a paraphrasing of bowies "Life on Mars"
> pneumatic
Interesting! Will check out.
> ... that in a few minutes I can load the context in my working memory and be forever satisfied once I'm done that this decision will never have to be made again
Okay this is an aspect I've not considered enough maybe. But this then applies mostly to decisions that can be phrased project-agnostic.
> My understanding of your implication is that this isn't worthwhile
No. I actually think it is worthwhile!
But I don't think it differs substantially from just having an ad-hoc project harness that's just a bunch of markdown and is maintained by the agents based on the discussions.
It seems to be hard because it compares the files with each other, not with decisions that were made in sessions.
In Substrate you can see what is in memory and select what each agent sees.
Does decoherence show first in instructions or in generated code?
https://trysubstrate.co/l/a3hn
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 do this.
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!
Can you clarify what "load the spec hierarchy in as context" as I am not sure if you mean "the files rooted here and below" (which makes sense to me, as intuitively that's a near-decomposable, decoupled description of your hierarchical system); or do you mean "the files above us in the hierarchy" (which describe supersets of context that live above the feature and help inform it)?
I'm not sure what you mean by "hammering" git — git is a robust version control and the overhead for commits is not big.
I don't think it makes sense for git to be overloaded with process information, rather I think it makes sense that, in the same way we have different mechanized programming languages (structured around compilers), we are going to have various standards of deliberative programming (structured around ???) — if you go on WakaTime, you'll see that a growing share of programming is done in Markdown.
I think it can make sense to have them next to the source code, but this introduces a couple problems like fragmentation of these records (perhaps mitigated if they follow naming conventions like test records do in certain languages/frameworks), and it introduces guesswork to know where cross-section work is documented: I would be curious how you've resolved that?
In this framework, the records live in docs/adr, and we've solved the problem of tight integration with deep-linking (adr://v1/repo/<owner>/<repo>/adr/<n>#<anchor>) and path-independent references. These, or shortcuts (like "adr-0002#qst-how-do-we-do-X"), are used in the code to avoid the problem you're correctly referencing of epistemic drift.
Re: Y-statements, thanks for the reminder, I forgot about those (for other readers, it's a template sentence: "In the context of …, facing …, we decided …, to achieve …, accepting …"). They are completely compatible and complementary with the decision section ORRCF format (I noticed the acronym is explained in the top comment so I won't keep explaining it).
A talk from Google Deepmind I heard at Princeton ("We Can't Understand AI Using our Existing Vocabulary") argued convincingly that the problem we encounter with models is one of total incomprehension. We are two very different ways of perceiving, processing, and thinking. We need to create more surface for communication and exchange, we need scaffold conversation more.
The models are trained to be cybernetic: To take your wishes and make it their command with as little interruption as possible. Even if they've now been encouraged to surface some questions, there's so much that is just taken away and that is decided. If you are interested in speed that's perhaps useful, but there's also a design space that is foreclosed from you that way.
At any rate, the models here are encouraged to: - Structure the braindumps of the human, flesh them out and resolve any open questions they can on their own - Surface, to the human, the tensions they can't resolve alone under the form of ORRCF questions
This is precisely calibrated to become a medium that, far from being about ceremony, is about resolving misunderstandings in the present.
Over time, the models get to know you not just by your instructions of what to do, but also by you providing more definition to your own thinking, such that it becomes easier for them to generalize it across new decisions and (if you import records) across new projects.
Re: your "despite specific instruction", yes, teachability is a big deal: I've been working most of the last few months putting together skills, MCPs, etc., and it's clear that providing granular and expansive documentary support is important. I suggest the plugin, adrs4ai/plugins, that you can already install and that I hope to be on the Anthropic Marketplace eventually!
Thanks for your interest and your thoughts, and I'd be interested if you have any more!
A hard part of this approach is scoped rules: you still need a human to decide which records are still true.
What we try to do at Substrate with our memory is to automate this: 1 memory outside of any agent, where all the facts have their source.
Did the agent-written records go stale or just pile up?
https://trysubstrate.co/l/a3hn
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.
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...
https://github.com/architecture-decision-record/architecture...
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/).
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.