Your team used to ship features in 2 days. Now the same features take 2 weeks. Nobody knows why — the codebase looks "fine." This invisible drag on velocity is technical debt, and it's the most common reason engineering teams slow down.
What is technical debt?
Technical debt — sometimes called tech debt or code debt — is the cost of shortcuts in your code that you'll pay for later. It's the gap between how your code is and how it should be.
The term was coined by Ward Cunningham in 1992 as a metaphor: like financial debt, you borrow speed now and pay interest (bugs, slowdowns, rewrites) later. The technical debt definition has evolved since then, but the core meaning remains: deferred quality that compounds over time.
Unlike financial debt, technical debt compounds silently. Nobody sends you a bill. One day your team realizes a 2-day feature now takes 2 weeks — that's the interest payment.
The 5 types of technical debt
Not all tech debt is the same. Understanding the types of technical debt helps you prioritize what to fix first.
1. Architecture debt
When code violates your intended architecture. A NestJS service in domain/ importing directly from infrastructure/. A controller calling the database directly instead of going through a service.
// ❌ Architecture violation: domain depends on infrastructure
import { PrismaClient } from '@prisma/client'; // infrastructure concern
export class OrderService {
private prisma = new PrismaClient(); // domain should not know about Prisma
}
// ✅ Depend on abstractions
export class OrderService {
constructor(private readonly orderRepo: OrderRepository) {} // clean
}Why it happens: AI code generators don't know your architecture rules. They generate working code without respecting layer boundaries.
2. Runtime risk debt
Code that works in development but crashes under production load. Synchronous file reads, blocking crypto, busy-wait loops — all inside request handlers where they block the event loop.
// ❌ Blocks the event loop for ALL concurrent users
app.get('/config', (req, res) => {
const data = fs.readFileSync('./config.json', 'utf8');
res.json(JSON.parse(data));
});
// ✅ Non-blocking
app.get('/config', async (req, res) => {
const data = await fs.promises.readFile('./config.json', 'utf8');
res.json(JSON.parse(data));
});3. Performance debt
Queries and operations that scale poorly. The classic N+1 query, unbounded findMany() on a 50M-row table, or sorting millions of records in JavaScript instead of the database.
// ❌ Fine with 100 rows, OOM crash with 50M rows
const allEvents = await prisma.event.findMany();
// ✅ Always paginate
const events = await prisma.event.findMany({ take: 20, skip: page * 20 });4. Reliability debt
Fire-and-forget promises, HTTP calls without timeouts, empty catch blocks. Code that works 99% of the time but fails silently the other 1% — losing data and causing cascading failures.
// ❌ If this fails, nobody knows
sendWelcomeEmail(user.email); // no await, no error handling
// ✅ Explicit error handling
try {
await emailQueue.add('welcome', { email: user.email });
} catch (e) {
logger.error('Failed to queue welcome email', e);
}5. Maintainability debt
High cyclomatic complexity, code duplication, dead code, missing tests. This doesn't crash production — it slows your team down. Every new developer takes months to understand the codebase. Bug fixes in one place break another.
Technical debt examples (real code)
Here are concrete technical debt examples from real Node.js projects:
Example 1: A Prisma query inside a for loop creates N+1 queries. With 10 users it's 11 queries. With 10,000 users it's 10,001 queries — exhausting the connection pool.
Example 2: crypto.pbkdf2Sync() in a login handler blocks the event loop for 100-500ms per request. During peak traffic, the entire API becomes unresponsive.
Example 3: An Express middleware does JSON.parse(req.body) without size limits. An attacker sends a 500MB JSON payload and crashes the process.
Example 4: A NestJS service catches every exception with an empty catch block. Payments fail silently, users are charged but orders aren't created.
How to measure technical debt
You can't reduce what you can't measure. Here's how to measure technical debt effectively:
Debt score: A single number (0-100) that represents overall code health. Technical Debt Radar uses a weighted formula: architecture violations (+5 points), circular dependencies (+10), runtime risks (+8), N+1 queries (+8), complexity (+1 per point above threshold).
Violation counts by category: How many issues in each of the 5 categories? This shows where debt concentrates.
Trend over time: Is debt growing or shrinking? A debt score trending upward sprint over sprint means you're accumulating faster than you're paying down.
These technical debt metrics give you a concrete basis for prioritization instead of gut feel.
How to reduce technical debt
Effective technical debt management follows four steps:
Step 1: Scan your codebase.
npx technical-debt-radar scan .Get a baseline. Know exactly where debt lives and how severe it is.
Step 2: Prioritize by impact. Runtime risks and N+1 queries on large tables are emergencies. Architecture violations are important but less urgent. Complexity is a long-term concern.
Step 3: Set up PR gates. Stop accumulating NEW debt while you pay down old debt. A PR gate that warns (or blocks) on new violations prevents the problem from growing.
Step 4: Track trends. Monitor your debt score weekly. Celebrate when it goes down. Investigate when it goes up.
This approach to reducing technical debt works because it combines detection, prevention, and measurement.
Tools for technical debt detection
Several technical debt tools exist, each with different strengths:
SonarQube: General-purpose code quality. 30+ languages. No runtime detection or architecture enforcement. Best for multi-language enterprises.
CodeScene: Code health trends and hotspot analysis. Good for understanding where debt concentrates over time.
ESLint: Syntax rules and code style. No architecture enforcement, no ORM analysis, no scope awareness.
Technical Debt Radar: Node.js-specific. Scope-aware (handler vs background), volume-aware (table sizes), architecture enforcement via YAML policy. 47 patterns, 0 false positives.
Start detecting technical debt automatically
Run one command to find every instance of technical debt in your Node.js project:
npx technical-debt-radar scan .First scan is free. No account needed. 47 detection patterns across 5 categories. Results in under 10 seconds.