docs(10_Wiki): 위키 전체 재구성 — Topic_* 폴더를 4개 카테고리로 통합 + 대규모 중복 제거
Topic_Agent/Topic_Blog/Topics/Topics_Biz/Topics_Meeting/Topics_Rag의 마크다운 지식 문서를 Topic_General/Topic_Programming/Topic_Graphic/Topic_Business 4개 카테고리로 재분류. - 중복 제거: frontmatter의 status:duplicate/merged + duplicate_of/redirect_to 필드로 자기 자신을 중복으로 선언한 리다이렉트 stub 1032개 제거, 완전 동일 내용 파일 472개 제거, 동일 파일명·다른 내용 충돌 시 더 큰(완전한) 버전만 유지(162개 제거) — 총 1639개 중복 제거. - 분류: 폴더 단위로 명확한 항목(AI_and_ML/Coding/Architecture 등 → Programming, Comfyui/Visual_Effects → Graphic, Topics_Biz/Topics_Meeting/사업 등 → Business, Poetic_Blog_Writing/창의성/Game_Design 등 → General)은 폴더 우선순위로, 나머지 혼재 폴더(Topic_Agent/Topic_Blog/Topics 루트/Thinking & Reasoning/Other/UI_UX_Assets)는 title/tags 키워드 스코어링으로 파일 단위 분류(불명확한 경우 General로 폴백). 원본 폴더명은 "From_*" 서브폴더로 보존해 추적 가능성 유지. - 최종 배치: Programming 2784 / General 1608 / Graphic 285 / Business 249 = 4926개 문서. - 에이전트 운영 상태(.astra/.agent/.obsidian/sessions/memory/_company/docs/lessons/_shared/src)는 지식 콘텐츠가 아니므로 재분류 대상에서 제외하고 원위치 유지. - Topics/Topic_email(상위 보호 폴더 Topic_email과 파일명 100% 중복) 삭제 — 보호 폴더 자체는 미변경. - 완전히 비게 된 Topic_Agent/Topic_Blog/Topics_Biz/Topics_Rag 폴더 제거.
This commit is contained in:
Antigravity Agent
@@ -0,0 +1,171 @@
|
||||
---
|
||||
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 |
|
||||
Reference in New Issue
Block a user