Technical debt is the most abused metaphor in software engineering. Every shortcut gets labeled “tech debt.” Every framework migration gets justified as “paying down tech debt.” The term has become so elastic it is almost meaningless. At Harbor Software, we have been building for about six months now, and we have accumulated our share of debt—some deliberate, some accidental, some that has already cost us more than the time it saved. This post is an honest accounting of what technical debt actually looks like at a 4-person startup, what it costs in practice, and how we decide what to fix versus what to live with.

The Ledger: What We Owe

Let me be specific about what our debt looks like right now, in February 2022. No abstract theorizing—here is the actual list:

1. No database migrations. We modify database schemas by running raw SQL in a shared Google Doc. There is no version history, no rollback capability, and no way to reproduce the production schema from code. Estimated cost to fix: 3 days.
2. Hardcoded configuration. API keys, model paths, feature flags, and threshold values are scattered across 14 Python files. Changing the embedding model requires editing 6 files. Estimated cost to fix: 2 days.
3. No integration tests. We have unit tests covering 62% of our codebase, but zero tests that verify the full request-response cycle through our API. Every deployment is a manual smoke test where someone opens a terminal and runs a curl command against the staging server. Estimated cost to fix: 5 days.
4. Copy-pasted error handling. The same try/except/log pattern is duplicated in 23 places, with slight variations in log format and error categorization. Some log to stderr, some to a file, some to our monitoring service. Estimated cost to fix: 1 day.
5. Monolithic inference module. All model loading, preprocessing, inference, and postprocessing lives in a single 1,200-line file called inference.py. Adding a new model type requires understanding the entire file because the control flow jumps between sections unpredictably. Estimated cost to fix: 4 days.

Total estimated cost to fix everything: 15 engineering days. With four engineers, that is roughly one full sprint dedicated to debt reduction. As of this writing, we have done none of it. The question is whether that is a rational choice or a mistake. The answer, it turns out, is both—depending on which item you look at.

Deliberate vs. Accidental Debt

Martin Fowler’s technical debt quadrant (deliberate vs. inadvertent, reckless vs. prudent) is a useful framework, but it misses a practical dimension: whether you knew the cost at the time of the decision.

Item 1 (no database migrations) was deliberate. We had three tables and two developers. Setting up Alembic, writing initial migrations, configuring the migration runner in our deployment pipeline—all of this felt like overhead we did not need. We knew we would need it eventually, and we made a conscious bet that “eventually” was more than three months away. That bet was correct—we have survived six months without it—but the compound interest is now visible. Every schema change takes 30 minutes of coordination (writing the SQL, sharing it in Slack, confirming everyone ran it, checking staging, then checking production) instead of running alembic upgrade head.

Item 5 (monolithic inference module) was accidental. No one decided to put everything in one file. It started as 200 lines of clean code that loaded one model and ran one type of inference. Then we added a second model type with different preprocessing. Then a third. Then batch inference. Then async inference. Then model caching. Each addition was small and reasonable in isolation. The file crossed 500 lines in October, 800 in November, and 1,200 in January. Nobody noticed because the growth was gradual, and each commit only added 30–50 lines to an already-large file.

This distinction matters for prevention. Deliberate debt requires better decision-making frameworks—specifically, better estimates of when “eventually” will arrive. Accidental debt requires better detection mechanisms—code review standards that flag file size, complexity metrics in CI, or even a simple Slack bot that alerts when a file exceeds 500 lines.

Measuring the Actual Cost

The cost of technical debt is not the cost of fixing it. That is a common misconception. The real cost is the ongoing tax you pay while living with it, multiplied by the time until you fix it. Here is how we measure that tax for each item:

Cost Formula: (time lost per occurrence) x (occurrences per month) x (months until fixed)

• No database migrations: 30 minutes extra coordination per schema change, 4 schema changes per month = 2 hours/month. Over 6 months: 12 hours total ongoing cost. The fix costs 24 hours (3 days). Breakeven point: 12 months from now. This is not yet worth fixing purely on time savings. However, there is a risk cost: if someone runs the wrong SQL or runs migrations out of order, we could corrupt production data. This risk is hard to quantify but real.
• Hardcoded configuration: 45 minutes per config change (finding all files, testing each one, deploying), 3 changes per month = 2.25 hours/month. Over 6 months: 13.5 hours. The fix costs 16 hours. Breakeven point: 7 months from now. Getting close to worth fixing, especially since config changes are accelerating as we add customers.
• No integration tests: 90 minutes of manual smoke testing per deployment, 8 deployments per month = 12 hours/month. Plus, two incidents in the last three months that took 3 hours each to diagnose because they would have been caught by integration tests = 18 additional hours. Total: approximately 14 hours/month including incident cost. The fix costs 40 hours. This has already cost us almost triple the fix over six months. We should have fixed this three months ago.
• Copy-pasted error handling: Occasionally causes confusion when debugging (inconsistent log formats), but the actual time cost is maybe 15 minutes per month. The fix costs 8 hours. Breakeven: 32 months. Not worth fixing on time savings alone.
• Monolithic inference module: 45 minutes extra per feature that touches inference (understanding the 1,200-line file, finding the right section, testing without breaking other models), 6 inference features per month = 4.5 hours/month. The fix costs 32 hours. Breakeven: 7 months. Worth fixing now, especially since inference work is accelerating.

The math makes the prioritization obvious. Item 3 (integration tests) is costing us the most by a wide margin and should have been fixed months ago. Item 4 (copy-pasted error handling) is barely noticeable in daily work despite being aesthetically offensive. Aesthetic concerns and real economic costs are often uncorrelated.

The Compounding Effect

What the simple cost formula misses is compounding. Technical debt does not grow linearly. It grows super-linearly because debts interact with each other in ways that multiply their individual costs.

Our hardcoded configuration (item 2) makes our monolithic inference module (item 5) worse. When a configuration value is hardcoded deep inside a 1,200-line file, you cannot just search-and-replace—you have to understand the context around each hardcoded value to know whether changing it is safe, whether other hardcoded values depend on it, and whether the change affects multiple model types or just one. Two manageable debts become one nasty tangle that takes longer to navigate than either would alone.

Similarly, our lack of integration tests (item 3) makes every other debt more expensive to fix. Without integration tests, you cannot confidently refactor the monolithic module because you have no automated way to verify you did not break something. Without refactoring confidence, the module keeps growing because nobody wants to touch it. Without a smaller module, configuration is harder to extract because you cannot see the clean interfaces. The debts form a dependency graph that increases the cost of addressing any individual item.

This compounding effect is why startups that ignore technical debt for 18–24 months often hit a wall where velocity drops 60–70% seemingly overnight. The debt did not appear overnight—it compounded gradually until the aggregate tax exceeded productive capacity. By the time teams notice, the cost of fixing everything has grown to 2–3 months of dedicated work, which feels impossible to justify when there are features to ship.

The Speed Illusion

The most dangerous rationalization in early-stage startups is: “We need to move fast, we will clean this up later.” This is true sometimes and catastrophically wrong other times. The difference lies in which shortcuts you take.

Shortcuts that genuinely accelerate you:

• Using SQLite instead of PostgreSQL for prototyping (easy to swap later, the interface is identical)
• Hardcoding a single customer’s branding (you only have one customer, and the abstraction is premature)
• Skipping internationalization (your market is English-only for the next year, and i18n is expensive to retrofit either way)
• Using a monorepo instead of microservices (correct at small scale anyway, and easier to extract later than to merge)
• Deploying to a single server instead of Kubernetes (K8s is overkill below 100K requests/day)

Shortcuts that create the illusion of speed while costing you net time:

• Skipping input validation (you will spend more time debugging garbage data than you saved skipping validation)
• No error handling (silent failures waste hours of investigation because you do not even know something went wrong)
• No logging (debugging production issues blind is extremely expensive—a single incident without logs can cost a full day)
• Copy-pasting instead of abstracting on the third occurrence (the fourth, fifth, and sixth occurrences will each require finding and updating every copy, and you will inevitably miss one)
• Skipping tests for code that handles money, authentication, or data integrity (the cost of a bug in these areas is orders of magnitude higher than the cost of writing the test)

The pattern: shortcuts that defer decisions you do not have information for yet are genuinely valuable. They preserve optionality while letting you move forward. Shortcuts that skip essential engineering hygiene—the practices that prevent bugs, enable debugging, and maintain code comprehension—always cost more than they save. The distinction is not about speed versus quality. It is about knowing which corners are safe to cut and which are load-bearing walls.

Our Debt Reduction Strategy

We do not have a “20% time for tech debt” policy. In my experience, those policies produce sporadic, unfocused cleanup that makes engineers feel productive without substantially reducing debt. Engineer A cleans up error handling in module X while engineer B rewrites the logging in module Y, and the systemic issues (no integration tests, monolithic inference) remain untouched because they are larger than what fits in a Friday afternoon. Instead, we use a structured approach:

Monthly debt review (1 hour). The whole team reviews the debt ledger, updates cost estimates based on actual data from the previous month, and identifies any new debts. This keeps the ledger accurate and prevents debt from becoming invisible. We discovered the integration test problem was worse than estimated during a monthly review when we counted the actual time spent on manual smoke testing—it was 40% higher than our initial estimate because we had been underreporting the time spent on incident investigation.

Fix debt when you touch it. If a feature touches a file with known debt, the feature estimate includes debt reduction time. Need to add a new model to the monolithic inference module? The estimate includes 4 hours of refactoring to extract a base class first. This prevents debt from blocking feature work while ensuring we address the highest-friction items first—because the items that cause the most friction are the ones that get touched most often.

Spike when the cost exceeds the threshold. When a debt item’s monthly cost exceeds 8 hours (one engineering day), we schedule a dedicated spike to fix it in the next sprint. Integration tests crossed this threshold two months ago; we are scheduling the spike now. Yes, we should have done it sooner. The threshold prevents us from ignoring expensive debt indefinitely.

Never fix debt that is not costing you. Our copy-pasted error handling (item 4) bothers every engineer who reads the code, but it costs us maybe 20 minutes per month in actual productivity. Fixing it would be satisfying but is not a good use of limited engineering time right now. Satisfaction is not a business justification. We will fix it when something else forces us into those files, or when the monthly cost rises above our threshold.

The Founder’s Role

Technical debt conversations in startups often devolve into engineers-versus-product-managers standoffs. Engineers want to fix everything; product managers want to ship features. Both positions are reasonable in isolation and counterproductive when absolute.

The founder’s (or CTO’s) role is to make debt visible and quantifiable. When you can say “skipping integration tests is costing us 14 engineer-hours per month and increasing our deployment risk,” the conversation shifts from subjective quality preferences to objective resource allocation. Product managers can engage with numbers. They cannot engage with “the code is messy.”

Quantification also protects against the opposite failure mode: over-engineering. When an engineer proposes a two-week refactor and you can show the existing debt costs 3 hours per month, the math does not justify the investment—the breakeven point is 27 months away, and in 27 months the entire module might be rewritten or deprecated. Both directions of error—too little debt reduction and too much—are costly. Measurement is the corrective for both.

At Harbor Software, our monthly debt review is attended by everyone including our product lead. There is no “engineers explaining technical problems to non-technical people” dynamic because the ledger uses hours and dollars, not code quality metrics. Everyone can participate in the prioritization because everyone understands the unit of measurement.

Conclusion

Technical debt is not inherently bad. It is a financing tool. Like financial debt, it can accelerate growth when used deliberately and destroy value when accumulated carelessly. The practices that keep it manageable are straightforward: maintain a ledger with specific items and specific costs, measure those costs empirically from real data, fix debt when you touch it, schedule spikes when monthly costs exceed your threshold, and never let aesthetic preferences masquerade as economic arguments. Six months into Harbor Software, we have debt we are comfortable carrying (no migrations, copy-pasted error handling) and debt we should have addressed sooner (integration tests). The difference between those categories was only visible in retrospect, which is why the monthly review matters—it shortens the feedback loop between accumulation and recognition, turning a six-month surprise into a monthly adjustment.

A Template for Your Own Debt Ledger

If you take one thing from this post, let it be the ledger. Here is the format we use, which you can copy into a spreadsheet or Notion database and start populating today:

• Item name: Short description of the debt (e.g., “No database migration framework”)
• Category: Deliberate or accidental
• Date identified: When the team first recognized this as debt
• Time cost per occurrence: How many minutes does this cost each time it causes friction?
• Occurrences per month: How often does this friction happen?
• Monthly cost: The product of the previous two fields, in engineer-hours
• Fix cost: Estimated engineer-days to resolve completely
• Breakeven point: Fix cost divided by monthly cost—how many months until the fix pays for itself
• Risk factor: Beyond time cost, does this debt create production risk, data integrity risk, or security risk?
• Status: Watching, scheduled, in progress, or resolved

Review this ledger monthly with the entire team—engineers, product, and leadership. Update the numbers with actual data from the past month, not estimates. Move items from “watching” to “scheduled” when their monthly cost exceeds your threshold (ours is 8 hours) or when their risk factor becomes unacceptable. Move items to “resolved” only after the fix is deployed, verified, and the monthly cost has actually dropped to zero. The ledger is a living document, not a wish list. Treat it like a financial statement: accurate, current, and the basis for investment decisions.