- An ADR is a document that records design decisions. The author writes that ADRs entrusted to AI gradually developed section structures that drifted, and that decision text came to include code details such as screen menu lists and constants.
- The author proposes checking structural rules that a machine can verify, such as section order, Status values, references between ADRs, and whether linked files exist, with a policy file that fails CI on violations. Semantic rules, such as whether a document reads like a specification, are judged by an LLM and left only as warnings on the PR.
- regomark is a command-line tool the author built. It analyzes Markdown and checks rules with OPA (a policy evaluation tool). The author states that there is no ADR-specific implementation and that the rules live in the policy file of the repository that uses it.
- When the author re-read 7 of their own repositories, they report that everything that differed from the code was detail that did not need to be in the ADR, and that the decisions and guarantees to be kept were not outdated. This is one author's observation.
O: This could work for a scene where a developer who wants to hand ADR review to AI and automatically catch format mismatches on every PR puts a .regomark/policy policy in one repository and runs regomark check in CI.
X: The author directly states that the semantic check is judged by an LLM, so the same ADR can get different answers on each run. Before deciding how much to trust the warnings, this needs to be checked.