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.