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

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

id	title	category	status	canonical_id	aliases	duplicate_of	source_trust_level	confidence_score	verification_status	tags	raw_sources	last_reinforced	github_commit	tech_stack
wiki-2026-0508-technical-debt	Technical Debt	10_Wiki/Topics	verified	self	기술 부채 Tech Debt Code Debt	none	A	0.93	applied	architecture refactoring debt maintainability		2026-05-10	pending	language framework agnostic 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

// 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)

# 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)

# 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)

// 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

// 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

// 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
• 변형: 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