Intro: what technical debt is, and isn't#
Technical debt = an architectural compromise made today for speed, paid back tomorrow. The concept comes from Ward Cunningham: "The first version may be inadequate, but if shipped, we learn; we borrow money + pay interest."
Conscious technical debt ("let's keep this Stripe webhook simple now, harden it later") is fine. Unconscious technical debt — who, when, why is unclear; nobody fixing it — is poison. The difference: conscious debt is tracked.
This article lists 6 disciplines for preventing + measuring + paying back tech debt. No project is debt-free; the goal is to slow accumulation + stay aware.
1. Architecture Decision Record (ADR) — decisions in writing#
ADR: a one-page file for every major architectural decision. "Why Postgres?", "Why a monolith?", "Why Zustand instead of Redux?" — context + alternatives + outcome.
Without ADR: a developer joining 6 months later can't answer "why is this set up this way?" — they either break it or layer something on top, complicating the situation. With ADRs, conscious debt becomes visible.
Practical:
/docs/adr/ directory, file 0001-postgres-choice.md. Template: Context → Decision → Consequences. 5-10 minutes to write; saves hours 6 months later.2. Code review discipline — catch debt at the door#
Rule: nothing merges without review. At least 1 approval (2 for critical paths). Review must be real — not a "LGTM" stamp; a line-by-line read.
Review checklist: (a) are names clear (variable, function, file)? (b) tests added (for critical logic)? (c) error handling done? (d) documentation updated? (e) any debt fixable now?
Common trap: a review comment is merged with "we'll fix it later." "Later" never comes. If the comment is a bug, fix it; if nice-to-have, file an issue and add to backlog. "Later" in the backlog is tracked debt; spoken "later" is lost.
3. Test pyramid — write the right kind of test#
Plenty of unit tests, moderate integration, few E2E. Each level has a different job: unit (does this function work?), integration (do modules talk correctly?), E2E (does the user scenario work?).
PR rule: unit tests required for critical logic (auth, payment, data transformation, business rules). E2E for UI components (Playwright). Don't test everything; test the right things.
CI mandatory: test failure blocks merge. Coverage targets: 85%+ for business logic, 70%+ for UI. Coverage isn't sufficient on its own, but it's a baseline you don't drop below.
4. Debt measurement — "how much do I owe?"#
Unmeasured debt can't be managed. Measurement tools: SonarQube / Code Climate (cyclomatic complexity, duplication, code smells), npm audit (security vulns), Lighthouse (performance), Sentry (error rate).
Numbers to watch: (a) count of high-complexity functions (50+ cyclomatic), (b) percent duplicated lines, (c) outdated dependency count, (d) average PR review time (longer = more team fatigue).
Reflect these on a weekly dashboard. Intervene if the trend turns negative (complexity rising every week). The static number doesn't matter as much as the trend: is debt accumulating or shrinking?
5. Refactor cadence — 20% of every sprint#
Conscious rule: 20% of every sprint goes to refactor. Not new features; improving the readability + test coverage + performance of existing code.
Without that time, what happens? Debt accumulates, velocity drops, team morale falls, eventually "rewrite from scratch" comes up. Rewrite cost is always 5-10× the cost of incremental renewal.
Which refactors? (a) SonarQube top 10 hotspots, (b) 6+ month-old dependency upgrades, (c) cleanup of frequently-touched modules, (d) areas the team is "afraid to touch". The last one is critical — the feared zone is the most rotted.
6. Documentation discipline — written knowledge always wins#
If knowledge behind a piece of code lives in someone's head, that knowledge is lost. Senior developer leaves, forgets, takes vacation — and the knowledge is gone.
Minimum documentation: (a) README (how to run, env vars, deploy instructions), (b) ADRs (architecture decisions), (c) API contracts (OpenAPI / GraphQL schema), (d) runbook (what to do during a critical incident).
Practical: documentation is updated in the same PR as the code. If it isn't, the review is rejected. "We'll write it later" → never gets written. Discipline becomes culture over time.
Conclusion: debt won't be zero, but it must stay visible#
No project is debt-free; that's natural. The problem isn't debt — it's invisible debt. The discipline of ADR + review + test + measurement + refactor + documentation makes debt visible and manageable.
The most critical of the 6? Code review. Because review enforces the other 5. Without review culture, ADRs aren't written, tests aren't added, documentation isn't updated. Review is the gate of discipline.
If you want to set up quality + sustainability discipline for your web software project, get in touch via our web software page — we install these six disciplines into teams.
Related articles
Other articles that support the same decision
SaaS
The First 7 Mistakes Teams Make in SaaS Architecture
Why SaaS products get expensive when tenant isolation, permissions, billing, and observability are not planned early.
AI Tools
What is Claude AI? A Comprehensive 2026 Developer Guide
Comprehensive guide to Claude AI's 2026 capabilities — Claude Code, MCP, API integration, KVKK compliance, and enterprise case studies for software developers.
Cost Analysis
Mobile App Cost in 2026: What Actually Sets the Price?
$10K or $200K? Mobile app cost is set by 7 line items: scope, backend, integrations, native need, testing+security, maintenance, phased approach. Concrete ranges per item.
Next step
If you are planning a similar project, we can clarify the scope and shape the right proposal flow together.
Start a project request