2nd/10_Wiki/Topics/Architecture/Technical_Debt.md

---
id: wiki-2026-0508-technical-debt
title: Technical Debt
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [기술 부채, Tech Debt, Code Debt]
duplicate_of: none
source_trust_level: A
confidence_score: 0.93
verification_status: applied
tags: [architecture, refactoring, debt, maintainability]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: agnostic
  framework: SonarQube/CodeScene
---

# Technical Debt

## 매 한 줄
> **"매 short-term shipping 의 가속 = long-term interest payment"**. Ward Cunningham 의 1992 metaphor — 매 financial debt 처럼 principal (수정 비용) + interest (매 feature add 의 slowdown) 의 구조. 매 2026 의 modern view 는 Martin Fowler 의 quadrant (deliberate/inadvertent × prudent/reckless).

## 매 핵심

### 매 Fowler quadrant
- **Reckless + Deliberate**: "we don't have time for design" — 매 worst.
- **Reckless + Inadvertent**: "what's layering?" — 매 ignorance.
- **Prudent + Deliberate**: "we'll deal with consequences later" — 매 acceptable, 매 documented.
- **Prudent + Inadvertent**: "now we know how we should have done it" — 매 unavoidable learning.

### 매 types
- **Code debt**: duplication, complexity, naming.
- **Design debt**: 매 architecture 의 wrong abstraction.
- **Test debt**: 매 missing/flaky test.
- **Documentation debt**: 매 stale README, missing ADR.
- **Dependency debt**: 매 outdated library, EOL runtime.
- **Infrastructure debt**: manual deploy, no IaC.

### 매 응용
1. Sprint capacity 의 20% 를 debt paydown 에 reserve.
2. ADR (Architecture Decision Record) 로 deliberate debt 의 documentation.
3. SonarQube / CodeScene 의 hotspot 분석 — 매 churn × complexity.

## 💻 패턴

### TODO with debt tracking
```typescript
// TODO(debt:DB-LOAD-001 2026-Q3): N+1 query — refactor to single JOIN.
// Acceptable now: 매 <100 users, 매 latency budget OK.
// Owner: @backend-team
async function getUsersWithPosts() {
  const users = await db.users.findAll();
  for (const user of users) {
    user.posts = await db.posts.findByUserId(user.id);
  }
  return users;
}
```

### ADR (Architecture Decision Record)
```markdown
# ADR 0042: Use in-memory cache for session store (deliberate debt)

## Status
Accepted

## Context
We need session storage. Redis cluster setup adds 2 weeks. Launch in 1 week.

## Decision
Use in-process Map<sessionId, Session> for v1.

## Consequences
- (+) Ship on time.
- (-) Sessions lost on restart.
- (-) Cannot scale beyond 1 instance.
- DEBT: Migrate to Redis when MAU > 10k OR before multi-region launch.
```

### Hotspot analysis (CodeScene-style)
```bash
# Find files with high churn × high complexity
git log --pretty=format: --name-only --since="6 months ago" \
  | sort | uniq -c | sort -rn | head -20 \
  | while read count file; do
      lines=$(wc -l < "$file" 2>/dev/null || echo 0)
      echo "$count $lines $file"
    done
```

### Boy Scout Rule (incremental paydown)
```typescript
// Before: legacy untyped
function processOrder(o) {
  if (o.s === 'p') { /* ... */ }
}

// After (touched this function for unrelated bug → improved):
type OrderStatus = 'pending' | 'paid' | 'shipped';
function processOrder(order: Order) {
  if (order.status === 'pending') { /* ... */ }
}
```

### Strangler fig migration
```typescript
// Route gradually from legacy to new
app.use('/api/users', (req, res, next) => {
  if (featureFlag.isEnabled('new-user-service', req.user)) {
    return newUserService(req, res, next);
  }
  return legacyUserService(req, res, next);
});
```

### Debt budget metric
```typescript
// Track debt as percentage of velocity
interface SprintMetrics {
  totalPoints: number;
  featurePoints: number;
  debtPoints: number;
  bugPoints: number;
}

function debtRatio(m: SprintMetrics): number {
  return m.debtPoints / m.totalPoints;
}
// Target: 15-25%. <10% = accumulating. >40% = stuck in mud.
```

## 매 결정 기준
| 상황 | Approach |
|---|---|
| Startup pre-PMF | Reckless OK, 매 ship fast |
| Post-PMF growth | Prudent deliberate, ADR everywhere |
| Mature product | 매 20% capacity to debt |
| Hotspot (high churn + complex) | Refactor next |
| Stable cold code | Leave it |

**기본값**: 매 deliberate + prudent + documented. 매 boy scout rule 의 매 PR.

## 🔗 Graph
- 부모: [[Software_Architecture]] · [[Refactoring_Best_Practices|Refactoring]]
- 변형: [[Code Smell]]
- 응용: [[Architecture Decision Record]]
- Adjacent: [[Boy Scout Rule]] · [[The Two Hats]]

## 🤖 LLM 활용
**언제**: debt categorization, ADR drafting, refactor prioritization, TODO format.
**언제 X**: 매 codebase-specific hotspot detection — 매 actual git history + tooling 필요.

## ❌ 안티패턴
- **"We'll fix it later"**: 매 later 가 안 옴.
- **Big bang rewrite**: 매 90% 가 fail (Joel Spolsky 2000).
- **Debt without ownership**: 매 nobody fixes.
- **Refactor sprint**: 매 isolation — 매 daily incremental 이 더 효과적.

## 🧪 검증 / 중복
- Verified (Cunningham 1992 OOPSLA experience report; Fowler 2009 quadrant).
- 신뢰도 A.
- 중복: [[Technical Debt (기술 부채)]] redirect.

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — Fowler quadrant + 6 debt types + paydown patterns |