Your Decision Log Is an Archaeological Site

I was building a small project with an AI coding agent when I realized my architecture documentation was failing both of us. The agent would start each session by reading through a growing pile of decision records, trying to reconstruct what was still true. I was doing the same thing every time I came back after a week away. The documentation existed. Nobody was getting value from it. ADRs Solve the Wrong Problem Architecture Decision Records are append-only by convention. When a decision changes, you don't update the old record — you write a new one that supersedes it. This sounds principled. In practice, it means your docs/decisions/ directory grows forever and the only way to understand the current state of the architecture is to read 40 files and mentally diff them against each other. The decisions that still matter? Maybe five of them. The other 35 are historical noise — half-abandoned ideas, constraints that evaporated when you switched libraries, debates that got resolved and th