refactor(topics): 멀티 에이전트용 지식 재편 — _Common(공통 기본기) + Domain_* 구조
에이전트 8종(대화형/프로그래머 C·S/디자이너/설계자/기획자/QA/PD/PM)에게 [공통 기본 능력 + 롤별 Specialty] 2층으로 지식을 주입하기 위한 재분류. 문서 내용·포맷은 무수정, 폴더 이동만 (6,372개 문서 수 보존 확인). - Topic_Programming → Domain_Programming (내부 구조 보존) - Topic_Graphic → Domain_Design - Topic_Business → Domain_Product - Topic_General → Domain_General - _Common 신설: Math(구 Topic_Math_Specialty), Reasoning(구 General/From_Thinking & Reasoning), Reasoning_Creativity(구 General/From_창의성), Communication(Poetic_Blog_Writing + From_writing) - 타 도메인의 From_* 폴더는 유지 (출처 표기일 뿐, 이미 도메인에 맞게 분류된 문서) - 빈 폴더 정리 (memory/procedures) - 에이전트→폴더 매핑은 workspace의 .astra/agent-knowledge-map.json (9개 에이전트) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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