Show 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!
评论
5 条预览评论 · 正在加载完整讨论请先登录 h4cker 账号，然后连接 Hacker News 后发表评论。
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.
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...
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.
Want to add a link to your work to the architecture decision record repo? I maintain it. https://github.com/architecture-decision-record/architecture...
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.