Tech debt is the metaphor that won. Almost every engineering organization on Earth now has a Jira label, a Notion doc, or a Slack channel with "tech debt" in the name. Almost none of them have a working definition of what counts, a way to measure how much they're carrying, or a budget to pay it down. The result is a backlog that grows every sprint, a CTO who keeps promising to "schedule a refactor quarter," and a team that's secretly spending half its time fighting the codebase instead of shipping. If you've already read our architecture decision record post, you know the cousin to this problem: tech debt is what happens when decisions go undocumented and the next engineer has to guess.
This guide is the pillar version. It covers what tech debt actually is (including the parts most people forget), where it comes from, what it costs, how to measure it, how to repay it without grinding shipping to a halt, and how to prevent it. We'll treat code, design, infrastructure, test, and documentation debt as a single family, because that's how they behave on a real product.
What is tech debt?
Tech debt is the future cost of every shortcut, omission, or suboptimal decision you ship today. The metaphor comes from Ward Cunningham, who coined it in 1992 to explain the trade-off between shipping fast and shipping clean (Wikipedia). His original framing was generous: a small, deliberate debt taken on to learn quickly is fine, as long as you pay it back before "interest" eats your future capacity.
The interest is the thing that catches teams. Every shortcut compounds. A duplicated function becomes three duplicated functions. A missing test becomes a culture of skipped tests. An undocumented endpoint becomes an entire API surface no one understands. By year three, your team is spending more time servicing the interest than building anything new.
A working definition for 2026: tech debt is anything in your system that makes the next change harder than it needs to be. That includes code, but also infrastructure, design, tests, and documentation. If a new engineer can't ship their first PR in a week because the codebase is hostile, that's debt. If your runbook is wrong and an on-call engineer ships a bad fix because they trusted it, that's debt. If your only architect left and her decisions live only in her head, that's debt.
Why does tech debt matter for SaaS founders?
Founders feel tech debt as velocity drag, not as a bug count. The first symptom isn't a broken build, it's a sprint that delivers half what the previous one did. The second symptom is engineers telling you "this should be a one-line fix" and then taking three days. The third is your best senior dev quietly looking for another job because the codebase is no longer fun to work on.
Stripe's Developer Coefficient research, which surveyed enterprise developers, found that engineers spend roughly 17 hours per week on bad code, technical debt, and rework, out of a 41.1 hour week (Stripe, 2018, widely cited and corroborated by later surveys). That's around 42% of paid engineering time spent fighting the past instead of building the future. McKinsey's analysis put a dollar figure on it: companies in their study reported that tech debt costs them 20% to 40% of the value of their entire technology estate, and CIOs estimated 10% to 20% of any new project's budget gets diverted to resolving debt before the project can even start (McKinsey, 2020). For a Series A startup that's burning $300k a month, 40% of engineering capacity is the difference between a 12-month runway and a 7-month runway.
The 2025 Stack Overflow Developer Survey echoed this: technical debt was among the top sources of frustration cited by professional developers (Stack Overflow, 2025). The interest payment is real, and engineers feel it before founders do.
What are the types of tech debt?
Most posts list "code debt and design debt." That's incomplete. A SaaS product accumulates debt in at least five distinct categories, and they require different responses.
| Type | What it looks like | Visibility | Cost to ignore | Difficulty to fix |
|---|---|---|---|---|
| Code debt | Duplicated logic, dead branches, copy-paste utilities, ignored linter warnings | Low (only devs see it) | Compounds with every PR touching the area | Medium - refactors are bounded |
| Design debt | Architectural shortcuts, monoliths that should be split, schemas that lie | Low until it's structural | Catastrophic - blocks whole features | Hard - often requires rewrites |
| Test debt | Skipped tests, brittle fixtures, no integration coverage, flaky CI | Medium (CI signals) | Bug rate climbs, deploys get scary | Medium - bounded but tedious |
| Infrastructure debt | Manual deploys, snowflake servers, secrets in env files, no IaC | Medium (ops feels it first) | Outages, security incidents, slow scale | Hard - touches production |
| Documentation debt | Missing READMEs, dead runbooks, outdated API references, no ADRs | High to users, low internally | Onboarding stalls, support load grows, bus factor of one | Easy if caught early, hard once it's deep |
Documentation debt is the category teams most often dismiss and most often pay the highest interest on. A poorly documented codebase makes every other debt category harder to address. You can't refactor what you don't understand. You can't migrate a service whose contract is undocumented. You can't onboard the engineer who would have helped you fix the rest. We covered the maintenance side of this in documentation maintenance and the per-component case in screenshots in docs technical debt. The pattern is the same in every category: ignored debt becomes structural.
The four quadrants framework
Martin Fowler's four quadrants is the cleanest way to triage what to pay down first. He splits debt across two axes: deliberate vs inadvertent, prudent vs reckless (Martin Fowler).
- Deliberate and prudent. "We know the right way, we're shipping the shortcut to hit a deadline, and we'll fix it next sprint." Fine, if you actually fix it.
- Deliberate and reckless. "We don't have time to do it right." This is most of the debt teams accumulate. It's a culture problem, not a code problem.
- Inadvertent and prudent. "We thought this was the right design. We learned more, and now we know better." Healthy. Every team produces some.
- Inadvertent and reckless. "We didn't know what we were doing." Common in junior teams or in domains the team doesn't understand. The fix is upskilling, not refactoring.
The triage rule: pay down deliberate-reckless debt first. It's the only quadrant that signals a process failure, and process failures compound faster than code does.
What causes tech debt?
The proximate causes are familiar: deadlines, context switches, evolving requirements, knowledge attrition. The deeper cause, in almost every team, is missing documentation of the original decision. When you don't know why something was built the way it was, every subsequent engineer makes a guess. Some of those guesses are wrong. The wrong guesses become permanent.
The most common drivers in a SaaS context:
- Deadline pressure. A board meeting, a launch date, a customer commitment. The team ships the version that works, not the version that's clean. Without a follow-up sprint to repay, the shortcut becomes the design.
- Evolving requirements. The product pivoted. The schema is from the old product. The new product is held together with type coercions and special-case branches.
- Knowledge attrition. The engineer who held the system in their head left. Their replacement is reasoning from the code, which is slower and more error-prone than reasoning from a design doc would have been.
- Skipped reviews. Code review caught architectural issues; nobody had time to fix them; they got merged anyway with a "TODO."
- Missing decision records. No ADR was written, so a year later the team relitigates the decision badly. We covered this pattern in detail in our architecture decision record post.
- Undocumented postmortems. An incident happened, the team firefought, no post-mortem was written, the same root cause hits again six months later.
- No design phase. Features get built without a design doc, so structural problems aren't caught at the cheap stage.
- No RFC discipline. Engineering decisions get made in DMs instead of in writing. We unpack the cost of this in our RFC template post.
If you sort your last 50 debt items by root cause, you'll find at least 30 of them trace back to one of the last four bullets. The fix isn't more refactoring. It's a process change.
How do you measure tech debt?
You can't pay down what you can't see. The honest answer is that no measurement is precise, but several are useful enough to drive decisions. Use more than one.
SQALE method. SQALE (Software Quality Assessment based on Lifecycle Expectations) estimates the cost of remediating violations in time-units. It's the framework SonarQube and similar tools surface as a "technical debt ratio," the cost of fixing all the issues divided by the cost of writing the code in the first place. A debt ratio under 5% is healthy. Above 20%, the team is in trouble.
Code churn. How often does the same file get edited? High-churn files concentrate complexity. They're not necessarily debt, but they're where debt hides.
Cycle time. How long does an average PR take from open to merge? If cycle time is climbing while team size is stable, you're paying interest.
Bug rate per KLOC. Bugs per thousand lines of code, segmented by service. A spike in one service is a tell.
Onboarding time. How long does a new engineer take to ship their first non-trivial PR? In a healthy codebase, that's two weeks. In a debt-laden one, two months.
Hours per sprint on debt work. Tag debt-related issues. Track the percentage of points spent on them per sprint. Healthy teams sit around 15-20%. Above 40%, the team isn't shipping product anymore.
Doc freshness ratio. Percentage of docs updated in the last 6 months versus total. Below 50% is a warning. Below 25% means the docs are actively misleading users. Our post on internal documentation covers how to track this practically.
The metric that surprises founders most is onboarding time. It's downstream of every other type of debt, and it's the easiest one to measure.
Strategies to manage and repay tech debt
There is no clever shortcut. There are five strategies that work, and they work in combination.
The 20% rule
Reserve 20% of every sprint for debt repayment. Not "when we have time." A standing budget. Track it. The math: a team carrying 30%+ debt load that allocates 20% of sprint capacity to repayment will, over six months, cut the load roughly in half, assuming new debt grows at a normal rate. The rule fails the moment leadership cancels the 20% for a "critical" feature. Don't.
Dedicated debt sprints
Once a quarter, run a full sprint on debt only. The argument against is that it stops shipping. The argument for is that it's the only time engineers can do the larger refactors that don't fit in a 20% slice. The right answer in practice is to run one debt sprint per quarter and keep the 20% rule in the other 11 sprints. Both, not either.
A visible debt board
Every debt item gets a Jira ticket or Linear issue with a severity, an estimate, and a tag. The board is reviewed in a recurring 30-minute meeting. The goal is not to fix everything, it's to make the debt legible to leadership. Invisible debt is the kind that grows. Visible debt gets prioritized.
Refactor in the path of new work
When you touch a file to add a feature, leave it slightly cleaner than you found it. The Boy Scout rule. This works at the engineer level if culture supports it. It does not work as a top-down mandate, because the people enforcing it can't see the cost.
Hard budget caps
Some teams enforce a maximum debt ratio. If SonarQube reports above 15%, no new features merge until it's back below 15%. This is aggressive but effective for teams that have lost discipline. Use it as a forcing function, not a steady state.
How do you prevent tech debt?
The cheapest debt is the kind you never take on. Prevention is the highest-leverage place to spend engineering process effort.
Write decisions down before you code. ADRs and design docs are the structural fix for "we don't remember why we built it this way." When the next engineer needs to change something, they have the original constraints in writing. We have a full template in our architecture decision record and design doc template posts.
Run RFCs for non-trivial changes. The RFC discipline catches design problems while they're still cheap. Anything that touches more than two services or changes a public contract should go through an RFC.
Write postmortems on every meaningful incident. Postmortems surface debt that caused the incident. If you don't write them, you'll re-pay the same debt every time the same root cause fires. Our post-mortem template covers the format.
Maintain a documentation strategy and ownership model. A documentation strategy and documentation governance program are the difference between docs that decay and docs that compound. Without ownership, every page slowly drifts.
Pay attention to developer experience. A good developer experience program catches the small frictions that, in aggregate, become process debt. The 2025 developer survey data is consistent: tooling friction shows up near the top of pain reports every year.
Run a "stop the bleed" review on legacy systems. When you inherit a debt-heavy system, don't try to fix it all. Find the one or two changes that prevent new debt from accumulating. Stabilize. Then start paying down.
Tooling for tech debt management
Tooling alone won't fix the problem, but the right tools make debt visible enough to act on.
| Category | Tool | What it tells you |
|---|---|---|
| Code quality | SonarQube, CodeClimate, Codacy | Debt ratio, complexity, duplication |
| Static analysis | ESLint, Pylint, Rubocop, Clippy | Style and pattern violations |
| Test coverage | Codecov, Coveralls | Coverage gaps, especially in critical paths |
| Dependency health | Dependabot, Renovate, Snyk | Outdated and vulnerable dependencies |
| Performance | Datadog APM, New Relic, Sentry | Hot paths, slow queries, memory leaks |
| Architecture | NDepend, Structure101, ArchUnit | Cyclic dependencies, layering violations |
| Doc freshness | Custom audits, Docsio | Stale pages, broken links, missing references |
The trap is buying SonarQube, getting a debt ratio of 14%, and treating that as success while your design debt and documentation debt continue to compound. Code quality tools see code. They don't see the runbook that's wrong, the API endpoint that isn't documented, or the architectural decision nobody can find. For the docs side specifically, the failure mode is covered in our why developers don't read documentation post: docs that exist on paper but don't help in practice.
Real examples of tech debt
A few patterns worth recognizing, drawn from common SaaS situations.
The early-stage shortcut. A pre-launch startup hard-codes Stripe price IDs into the front-end because they're racing to demo day. Two years later, they have 40 components reading those IDs and a billing migration is a quarter-long project. The original shortcut took 30 minutes. The repayment takes 400 hours.
The monolith that should have been split. A B2B SaaS grows from one to seven product surfaces. The original monolith now contains all seven, with shared models and tangled deployments. Every release blocks every team. The "right" fix is service extraction. The realistic fix is a 12-month phased decomposition with feature flags. The cost of the original "we'll split it later" decision was 18 months of velocity drag across four teams.
The undocumented integration. A team integrated with a partner API in 2023. The original engineer wrote no docs, no ADR, and no runbook. In 2026, the partner deprecates an endpoint with 90 days notice. Nobody on the current team knows which calls the integration depends on. The investigation takes three weeks. The migration takes six. With an ADR and a runbook, the work would have been one sprint.
The opposite case: Stripe. Stripe's docs investment is the inverse. They spend more on documentation than most companies spend on a feature team, and the result is a developer experience that pulls in customers who would have otherwise gone to a competitor. Their documentation isn't a cost center. It's a moat. The point isn't that you should match their spend. It's that great docs are the fastest way to reduce every other type of tech debt, because every refactor, migration, and onboarding gets cheaper when the documentation is honest.
Where Docsio fits
Documentation is the highest-leverage tech debt to fix because it amplifies all other debt. Poor docs make code debt harder to address (you can't refactor what you don't understand), make onboarding harder (new engineers can't help you fix the rest), and make architectural decisions harder to revisit (no one remembers why anything was built the way it was).
Docsio reduces documentation debt at two points: at write time, by auto-generating docs from your existing source, and at maintenance time, with an AI agent that catches stale pages, broken links, and drift before users do. It works whether you're starting from a URL, a codebase, or an existing docs site that's slowly rotting. The free tier is enough for a single-product startup. The Pro tier adds doc versioning, team collaboration, password-protected docs, and the AI chat widget that lets your customers query the docs in natural language. If documentation is currently the biggest entry on your debt board, start a project and let the AI agent take the first pass.
Frequently asked questions
What is tech debt in simple terms?
Tech debt is the future cost of any shortcut you take to ship faster today. The metaphor is financial: like a loan, you trade speed now for interest later. Unlike a loan, the interest rate isn't fixed, and it compounds every time someone else has to work around your shortcut.
Is tech debt always bad?
No. Deliberate, prudent debt is a normal part of shipping. The problem is debt that's never repaid, debt taken on without anyone realizing it, and debt that grows faster than the team can service. The bad version is "debt without a repayment plan."
What's the difference between tech debt and a bug?
A bug is behavior that doesn't match the spec. Tech debt is design that makes future bugs more likely. A duplicated function isn't a bug. The third time you copy it and forget to update one copy, you've shipped a bug. The debt was the prior condition.
How much tech debt is normal?
Most healthy teams carry a debt ratio of 5% to 15%, measured by tools like SonarQube, and spend roughly 15% to 20% of sprint capacity on debt work. Above 30% sprint capacity is a warning sign. Above 50% means the team isn't really shipping product anymore.
What's the biggest cause of tech debt?
Missing documentation of original decisions. Almost every long-lived debt item traces back to "we don't remember why this is the way it is, so we're making it worse trying to change it." Code shortcuts compound, but undocumented decisions compound faster.
How do you justify paying down tech debt to leadership?
Translate it into time. "We're spending 40% of every sprint working around X. Fixing X takes 6 weeks. After that, we recover 40% of velocity for the rest of the system's life." Founders who don't respond to "code quality" respond to "the next 18 months of feature velocity."
Are AI tools making tech debt worse?
It's mixed. AI-assisted coding can ship more code per engineer, including more debt-laden code, if the team isn't reviewing rigorously. AI-assisted documentation, on the other hand, is the first realistic answer to documentation debt, because the limiting factor was always writing time. Net effect depends on which side of that ratio your team uses AI for.
What's the best first step for a team drowning in tech debt?
Make the debt visible. Spend a week tagging every known debt item in your tracker, with a severity and an estimate. Don't fix anything yet. The triage data is more valuable than any individual fix, because it tells you which categories are actually hurting you.