Coding agents rewrite architectural decisions when the current code suggests several plausible implementations but the accepted rationale is not available in their task context. The agent optimises the local change it can see, not the historical constraint it cannot.
The agent sees evidence, not intent
Source code is strong evidence of what exists, but weak evidence of why it exists. A compatibility adapter might be deliberate, temporary or accidental. A soft-delete column might encode a regulatory requirement or merely an abandoned feature. The implementation alone rarely distinguishes these cases.
An agent asked to simplify the code can therefore remove the very mechanism that preserves the decision. The resulting patch may be cleaner in isolation and worse for the product.
Instructions cannot contain the whole decision log
Repository instruction files are valuable for broad working rules: commands to run, directories to avoid and conventions to follow. They become less effective when they accumulate every historical decision. Long global instructions consume context, become hard to maintain and provide no reliable lifecycle for superseded records.
The better pattern is to keep entry-point instructions concise and give the agent a way to retrieve the decision relevant to the task, with a stable identifier and citation.
Rationale changes the implementation
A bare rule such as 'do not hard-delete users' can prevent one mistake. A decision record explaining the restoration window, affected data and consequences helps the agent design the surrounding workflow correctly. It can preserve tombstones, account for dependent records and propose tests that reflect the actual reason.
Rejected alternatives matter for the same reason. Without them, a later task can reopen a settled debate and spend tokens recreating arguments the team already evaluated.
A practical control loop
Before implementation, retrieve the relevant accepted records. During review, require the patch to cite any decision it changes or relies on. At merge time, run objective checks for explicitly classified constraints. When the team changes its mind, supersede the record through review instead of silently editing the code around it.