alt Hacker NewsIt 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.
Replies
[flagged]
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.
There are no easy shortcuts.