How to manage technical debt in a startup
How to manage technical debt in a startup
To manage technical debt in a startup, treat it like a credit card you opened on purpose: take it on deliberately to ship faster, track every charge in Linear with a cost-of-delay tag, and pay down 20 percent of capacity each sprint before the interest compounds. Most startup debt is the right call. The dangerous kind is the debt you took on by accident and never wrote down.
This post is the operating system: what debt actually is, when it tips into deadly, and how well-run teams keep it controlled.
What technical debt actually is (and what it isn't)
Ward Cunningham coined the term in a 1992 OOPSLA experience report. He was not talking about bad code. He was talking about shipping code you knew was incomplete, on purpose, to learn faster from real users, with a written plan to come back and refactor. The metaphor was financial: take on debt to buy speed, pay interest as slower future changes, retire the principal when you can.
That definition rules out the things people usually call debt:
- Bad code is not debt. Debt is the gap between your current design and what the design would be if you started over today knowing what you now know.
- Legacy code is not automatically debt. A 2017 Rails service that quietly handles 100k requests per minute is working software.
- Code you do not understand is not debt. It is missing documentation, which is a different problem with a different fix.
Martin Fowler's quadrant simplifies the rest: debt is either intentional or unintentional, prudent or reckless. Most startup debt is intentional and prudent. You shipped the MVP without auth caching because you did not yet have the users to need it. That is correct engineering, not a moral failure.
Why startup debt is the right call (most of the time)
The startup graveyard is full of perfectly architected products no one wanted. Pre-PMF, every line of code you write may get deleted in three months when you pivot. Over-engineering is the bigger sin because it is permanent: that abstraction layer you built to support five database backends will still be there when you discover you only ever needed Postgres.
The first version of Notion was an Electron app with a single SQLite file. Stripe ran on a monolith Ruby app for years. Airbnb's first booking flow was three founders manually emailing hosts. None of those teams were doing anything wrong; they were buying speed-to-PMF with debt.
The honest math: shipping a feature in 2 weeks with debt and learning it is wrong beats shipping it in 6 weeks clean and learning it is wrong. The information you get back is the same. The 4 weeks you saved are what matter. This is why we wrote a separate guide on how to estimate software development time accurately: underestimating the cost of clean is what drives most teams to over-engineer.
When debt becomes deadly (the 5x rule)
Debt is fine until pivots and refactors start taking 5x longer than they should. Below that threshold, you are buying speed. Above it, the interest exceeds your engineering revenue.
Four symptoms say you have crossed the line:
- A simple feature now requires touching 12 files. Adding a new field to a user record means coordinating changes across the database, the API layer, three frontend components, two background jobs, and a webhook receiver.
- Onboarding a new engineer takes 3 weeks instead of 3 days. The codebase has tribal knowledge when the only way to ship is to ask Slack what a function does.
- Every bug fix introduces two new bugs. This is the test-coverage proxy at work, and coverage alone is the wrong KPI.
- The team is afraid to deploy on Friday. Friday-fear is the single best leading indicator of structural debt.
If any two are true, the debt is no longer prudent. If all four are true, founders tend to call us and say, "We need to slow down to speed up."
The AI-native compression effect (what changed in 2026)
Here is the part most technical-debt advice from 2018 to 2022 gets wrong in 2026: the cost to retire certain kinds of debt has collapsed.
Every engineer on Cadence is AI-native by default, vetted on Cursor, Claude Code, and Copilot fluency before they unlock bookings. We track the actual delta from those tools across thousands of refactor sprints. The pattern is consistent:
| Debt type | 2022 cost to retire | 2026 cost to retire | Take on intentionally? |
|---|---|---|---|
| Test backfill | High (2 weeks) | Low (2 days) | Yes |
| Mechanical refactor (rename, extract) | Medium (1 week) | Low (1 day) | Yes |
| Dead-code removal | Medium | Low | Yes |
| Type narrowing (any to specific) | High | Low | Yes |
| Dependency upgrade (minor versions) | Medium | Low | Yes |
| Schema migration under production load | High | High | No |
| Multi-tenant data model rework | Very high | High | No |
| Replacing core auth provider | High | High | No |
| Framework migration (Vue 2 to 3) | High | Medium-high | Carefully |
The implication is non-obvious. Take on more cheap debt knowingly: retiring it is now a 2-day job for a senior with Claude Code. Refuse deadly debt at any speed; AI tools have not moved the needle on architectural rework or anything that requires understanding the business semantics of your data.
Test coverage is the cleanest example. In 2022, getting from 30 to 70 percent coverage on a 50k-line codebase was a quarter of senior engineering time. In 2026, the same job is roughly a week. Our AI-assisted refactoring playbook goes deeper on the workflows that compress this work.
The operating system: how to actually manage it
Most teams know they have debt. Most cannot tell you how much, where it lives, or what it would cost to retire. Debt management is mostly a visibility and ritual problem, not a technical one.
Five rules, in order:
1. Track every piece of debt as a Linear or Jira issue
If a piece of debt is in someone's head, it does not exist. The first time someone says "we should clean that up later," that sentence becomes a Linear issue with a tech-debt label. No exceptions. The act of writing it down forces you to decide whether the debt is real, and creates the artifact you will sort and prioritize later.
2. Tag every issue with a cost-of-delay number
A tech-debt label tells you nothing. A label like cost-of-delay: 4 hours/week tells you everything. Cost-of-delay means: how many engineer-hours per week are we losing right now by not fixing this?
A flaky CI step that costs each engineer 30 minutes a day across a team of 6 is a 15-hour-per-week tax. That is one of your top-priority issues, and the tag makes it obvious without anyone holding a meeting. Sort the backlog by cost-of-delay descending. The 5-line fix that saves 15 hours per week ships before the elegant refactor that saves 2.
3. Allocate 20 percent of each sprint to debt reduction
This is the adapted version of Google's old "20 percent time." One day per week, every engineer, every sprint. Booked, recurring, non-negotiable. Below 10 percent, debt grows faster than you retire it. Above 40 percent, you are probably ducking a feature decision. The 20 percent is taken from the cost-of-delay-sorted backlog, not from whatever is annoying the engineer that morning.
4. Apply the boy scout rule on every PR
Bob Martin's version: leave the campsite slightly better than you found it. Every PR is allowed (and quietly encouraged) to make small drive-by improvements to the file it touches. Rename a misleading variable. Delete a dead branch. Tighten a type. Done well, this retires debt continuously, in the background, with zero meetings. Done badly, every PR turns into a 600-line refactor nobody can review. A good code review culture, which we cover in our code reviews effectively playbook, keeps boy-scouting from sliding into rewrite-creep.
5. Schedule one full debt sprint per quarter
Once a quarter, run a one-week sprint where the only goal is a named refactor target. Not "clean up debt" in general; a specific named target like "consolidate our 3 user-state stores into one" or "delete the v1 booking endpoint and all its callers." Ship it, measure the speedup on the next 2 sprints, repeat.
Anti-patterns that look like debt management but aren't
Five patterns that feel responsible but are worse than doing nothing:
- The Big Rewrite. Joel Spolsky wrote about this in 2000 with Netscape 6 as the cautionary tale. The team agrees the codebase is unsalvageable. Twelve months later the rewrite is 80 percent done, missing the half of the original product nobody documented. Almost every rewrite we have watched cost more than the debt it was supposed to retire.
- Test coverage as the only KPI. 90 percent coverage on shallow tests that mock the database is worse than 60 percent coverage on integration tests that exercise the system. Track flake rate, mean-time-to-detection, and bug-fix-introduces-new-bug rate instead.
- "We'll fix it later" without a date. Denial in a Linear ticket. If a debt issue does not have a target sprint, it does not exist. It gets a date or it gets closed.
- Backlog dumping. The team opens 400 tech-debt tickets in three months, then nobody reads them. If you cannot keep the backlog under 50 active issues, you are recording, not prioritizing.
- Code freezes for refactor. Two-week freezes produce three weeks of merge conflicts and zero shipped features. If the refactor needs a freeze, it is too big and should be broken into smaller incremental changes. Our piece on scaling MVP to production covers the patterns that let you refactor live.
When you can skip this entirely
Best practices have ROI curves. Respect them.
Two founders pre-revenue with 10 users and no PMF: skip every ritual in this post. The debt is in your head. The fix is to find PMF.
Below 20k MRR or 3 engineers, a single shared Linear view called "tech debt" with a vague priority order is enough. Run the 20 percent rule informally.
Above 100k MRR or 5 engineers, the system in this post starts paying for itself within a quarter. Above 500k MRR or 10 engineers, not running it is malpractice. If you are getting close to needing a microservices migration, the debt management practice becomes a precondition, not a nice-to-have.
When to bring in outside help
Day-to-day debt management stays in-house. The team that wrote the code understands the trade-offs. Outsourcing your boy-scouting is a bad idea.
Structural refactors are different. A 2 to 4 week sprint to consolidate three state stores, replace a deprecated payment integration, or rewrite a flaky test suite is the shape of work where a fresh senior engineer is faster than your team. The team is too close to the code to see the obvious cuts. A senior coming in cold, with a clear scope and AI-native tooling, often ships in half the time.
The senior tier on Cadence ($1,500 per week) is the most-booked tier for refactor work specifically. The 48-hour free trial is enough to scope the refactor and either commit or walk away. Every engineer runs Cursor and Claude Code as their default workflow, which is what makes the 2026 cost numbers in the table above realistic. Before you book, audit your stack with Ship or Skip so you bring in a senior with a clear target.
Steps
- Open one Linear view called
tech-debt. Today, in ten minutes. No process design yet, just a view. - Write down the five biggest pieces of debt you can think of. One ticket each. No detail beyond "what is it" and "where is it."
- Add a
cost-of-delayfield to your Linear template. Estimate engineer-hours-per-week lost. Be honest. - Sort the view by cost-of-delay descending. This is your debt priority list.
- Block one day per week per engineer for debt work. Recurring, non-negotiable, pulled from the top of the sorted view.
- Schedule one full debt sprint per quarter. Pick one named refactor target. Ship it. Measure the speedup.
- Re-read the boy scout rule with the team. Get agreement on what "slightly better" means in your codebase, so PRs do not turn into rewrites.
Do not try to ship all seven steps in week one. Step 1 and step 2 are enough to start. The system compounds in your favor as soon as the debt becomes visible. If your team is too close to a structural refactor to make progress, book a senior engineer on Cadence for a scoped 2-week sprint and only commit past the 48-hour trial if the first two days produce real ground.
FAQ
What percentage of engineering time should go to technical debt?
20 percent is the working default for most pre-Series A startups: one day a week, every engineer, every sprint. Below 10 percent, debt grows faster than you retire it. Above 40 percent, you are probably ducking a feature decision.
Should we ever do a full rewrite?
Almost never. Rewrites kill more products than they save. The only honest cases are when the original framework is end-of-life and security patches have stopped shipping, or when the original codebase cannot legally support a new requirement (a hard data residency rule, a schema that violates GDPR by design). In every other case, incremental refactors win.
How do we know our debt is getting dangerous?
When the same simple feature takes 5x longer than the equivalent feature did six months ago. Track engineer velocity in shipped PRs per week, not story points. Story points absorb the slowdown invisibly; PR throughput does not.
Can AI tools fix our existing technical debt?
Mechanical debt, yes: AI tools (Cursor, Claude Code) reduce the cost of test backfill, type narrowing, dead-code removal, and dependency upgrades by roughly 5 to 10 times compared to 2022. Architectural debt, no. Schema migrations under load, multi-tenant data rework, and core auth replacement still require senior judgment. The AI tools speed up the typing, not the thinking.
Should we tell investors about our technical debt?
Yes, in financial terms. Frame it as "we accrued X engineer-weeks of debt to hit PMF; here is our 6-month retirement plan with cost-of-delay numbers." Sophisticated investors prefer honesty and a credible plan over a fictional clean-codebase story.
What should be in a technical debt ticket?
Four things, none long: what the debt is (one sentence), where it lives (file paths or system name), the cost-of-delay estimate (engineer-hours per week), and the proposed fix (one paragraph). More than that is over-engineering the bug tracker.