by buster 1 day 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.

lumbroso 8 hours ago

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.