Every engineer knows the feeling: you inherit a codebase, and something feels wrong. The patterns don't make sense. The service boundaries seem arbitrary. And no one can explain why things are the way they are.
The code isn't the problem. The decisions that shaped the code are.
The Uncomfortable Truth About Code
Here's something we don't talk about enough: code is disposable. The average piece of code gets rewritten every 2-3 years. Frameworks come and go. Languages fall in and out of favor.
But architecture? Architecture persists.
What Persists?
The decision to use microservices over a monolith. The choice of eventual consistency over strong consistency. The boundary between services. These decisions create constraints that outlive the code by years, sometimes decades.
Case Study: The $440 Million Decision No One Documented
Knight Capital Group
On August 1, 2012, a deployment reactivated dormant code from eight years earlier—code that no one remembered existed.[1]
The root cause wasn't the code itself. It was a series of undocumented architectural decisions:
- ?Why was the old "Power Peg" system kept in the codebase?
- ?What flag controlled its activation?
- ?Why did a new feature reuse that flag?
None of these decisions were recorded. When the original engineers left, the knowledge left with them.
Why Architecture Documentation Is Different
Code comments explain what. Architecture documentation explains why.
// Use cache to improve performance
cache.set(userId, userData);The code comment tells you nothing about why Redis, why 30 minutes, or what tradeoffs were made. The architecture decision record captures the thinking that led to the code.
The Research Is Clear
The Architecture Tradeoff Analysis Method (ATAM), developed at Carnegie Mellon's Software Engineering Institute, has over 1,000 research citations[2] validating a simple premise: architecture decisions have compounding consequences.
Amazon's Lesson: Architecture Is Organizational
When Jeff Bezos mandated the "two-pizza team" rule, he wasn't just restructuring org charts. He was making an architectural decision.
- Transition to microservices architecture
- Service-oriented architecture → AWS
- Independent team deployments
- Decades of architectural consistency
Amazon's architecture wasn't designed on a whiteboard. It emerged from an organizational decision that was documented, enforced, and persisted for decades.
The Real Cost of Undocumented Decisions
Research from McKinsey estimates developers spend nearly a third of their time dealing with technical debt.[4] But much of that "technical debt" is actually decision debt—the accumulated cost of not knowing why things were built the way they were.
When a senior engineer spends a week "investigating" a system before making changes, they're doing decision archaeology. They're trying to reconstruct the context that was never captured.
What This Means for You
If you're reading this, you're probably making architectural decisions. Maybe daily. The question isn't whether to document them—it's whether you can afford not to.
Every decision you make without documentation is a bet that:
- ⚠You'll remember the context in two years
- ⚠Everyone who needs to know will learn through osmosis
- ⚠Future engineers won't need to understand your constraints
That's a lot of bets. And they compound.
Start documenting your architectural decisions today.
Not because process is good, but because institutional memory is priceless—and far too easy to lose.
References
- [1]Dolfing, H. (2019). Project Failure Case Study: Knight Capital
- [2]Kazman, R. et al. (2000). ATAM: Method for Architecture Evaluation. Carnegie Mellon SEI
- [3]Koziolek, H. (2015). Sustainability evaluation of software architectures: A 15-year retrospective. Science Direct
- [4]McKinsey Digital (2020). Tech debt: Reclaiming tech equity