// A framework for deciding which architectural debts are worth taking on, which to refinance, and which will bankrupt you by year three.
Every architectural decision is a loan. You're borrowing speed today against complexity tomorrow. The interest rate varies. Some loans pay for themselves in a quarter. Some compound quietly for three years and then come due all at once, usually at the worst possible moment.
Most engineering organizations treat technical debt as a feeling — a vague sense that the codebase is "messy" or that "we should really refactor that." That's not a framework. A debt schedule is.
The three categories of architectural debt
Deliberate, prudent debt. You knew the tradeoff. You took the shortcut on purpose to hit a deadline or validate an assumption. You wrote it down. You scheduled the payoff. This is good debt — like a mortgage. It bought you something real and you have a plan to retire it.
Deliberate, reckless debt. You knew the tradeoff and took the shortcut anyway, with no plan to pay it back. This is the engineering equivalent of putting a vacation on a credit card and "figuring it out later." It compounds. It always compounds.
Inadvertent debt. You didn't know it was a tradeoff at the time. You picked a serialization format, or a tenant-isolation strategy, or a primary key shape that seemed fine. Two years later it's load-bearing and wrong. This is the most expensive kind because by the time you see it, half the codebase depends on it.
Reading your own balance sheet
Once a quarter, walk the codebase as if you were a new senior engineer joining the team. Write down every place where the answer to "why is it this way?" is "because we were moving fast" or "because the original person isn't here anymore." That's your debt schedule.
For each line, ask three questions:
- What's the interest rate? How much does this decision slow us down per week, per incident, per new feature?
- What's the principal? How big a refactor is it to fix correctly?
- When does it come due? At what scale, or at what feature, does this become a blocker rather than an annoyance?
Sort by interest rate, not by principal. The thing that costs you a day every sprint is more expensive than the thing that will cost you a month, someday, maybe.
What you actually do with the schedule
You pay the high-interest debts first. You consciously refinance — turn ad-hoc cleanups into one deliberate refactor with a written scope. You let the cheap debt sit. You stop pretending you'll fix everything, and you start treating the codebase like what it is: a balance sheet of decisions, some of which were correct and some of which weren't, and all of which are still earning interest.
Architecture is the easy part. The hard part is being honest about which decisions are paying off and which ones aren't.