## Tech Debt

프로젝트의 기술적 부채를 정량적으로 분석하고, 건전성 스코어와 개발 효율성에의 영향을 가시화합니다. 트렌드 분석을 통해 개선 상황을 추적하고, 시간적 비용을 산출하여 우선순위가 매겨진 개선 계획을 작성합니다.

### 사용법

```bash
# 프로젝트의 구성을 확인해서 기술적 부채를 분석
ls -la
"이 프로젝트의 기술적 부채를 분석해서 개선 계획을 작성해줘"
```

### 프로젝트 건전성 대시보드

```text
프로젝트 건전성 스코어: 72/100
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 카테고리별 스코어
├─ 의존관계의 신선도: ████████░░ 82% (최신: 45/55)
├─ 문서 충실도: ███░░░░░░░ 35% (README, API 문서 부족)
├─ 테스트 커버리지: ██████░░░░ 65% (목표: 80%)
├─ 보안: ███████░░░ 78% (취약점: 2건 Medium)
├─ 아키텍처: ██████░░░░ 60% (순환 의존: 3곳)
└─ 코드 품질: ███████░░░ 70% (복잡도 높음: 12파일)

📈 트렌드 (과거 30일)
├─ 종합 스코어: 68 → 72 (+4) ↗️
├─ 개선 항목: 12건 ✅
├─ 신규 부채: 3건 ⚠️
├─ 해소 부채: 8건 🎉
└─ 개선 속도: +0.13/일

⏱️ 부채의 시간적 영향
├─ 개발 속도 저하: -20% (신기능 개발이 통상의 1.25배 시간)
├─ 버그 수정 시간: +15% (평균 수정 시간 2h → 2.3h)
├─ 코드 리뷰: +30% (복잡성에 의한 이해 시간 증가)
├─ 온보딩: +50% (신규 멤버가 이해에 필요한 시간)
└─ 누적 지연 시간: 주 40시간 상당

🎯 개선에 의한 기대 효과 (시간 베이스)
├─ 즉시 효과: 개발 속도 +10% (1주후)
├─ 단기 효과: 버그율 -25% (1개월후)
├─ 중기 효과: 개발 속도 +30% (3개월후)
├─ 장기 효과: 메인터넌스 시간 -50% (6개월후)
└─ ROI: 투자 40시간 → 회수 120시간 (3개월)
```

### 기본 예

```bash
# 건전성 스코어의 상세 분석
find . -name "*.js" -o -name "*.ts" | xargs wc -l | sort -rn | head -10
"프로젝트 건전성 스코어를 산출해서, 카테고리별로 평가해줘"

# TODO/FIXME의 부채 임팩트 분석
grep -r "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" . --exclude-dir=node_modules --exclude-dir=.git
"이 TODO들을 부채 임팩트 (시간×중요도)로 평가해줘"

# 의존관계의 건전성 체크
ls -la | grep -E "package.json|Cargo.toml|pubspec.yaml|go.mod|requirements.txt"
"의존관계의 신선도 스코어를 산출하고, 업데이트의 리스크와 효과를 분석해줘"
```

### Claude와의 연계

```bash
# 포괄적인 기술적 부채 분석
ls -la && find . -name "*.md" -maxdepth 2 -exec head -20 {} \;
"이 프로젝트의 기술적 부채를 다음 관점에서 분석해줘:
1. 코드 품질 (복잡도, 중복, 보수성)
2. 의존관계의 건전성
3. 보안 리스크
4. 성능 문제
5. 테스트 커버리지 부족"

# 아키텍처의 부채 분석
find . -type d -name "src" -o -name "lib" -o -name "app" | head -10 | xargs ls -la
"아키텍처 레벨의 기술적 부채를 특정하고, 리팩터링 계획을 제안해줘"

# 우선순위가 매겨진 개선 계획
"기술적 부채를 다음 기준으로 평가해서 표 형식으로 제시해줘:
- 영향도 (높음/중간/낮음)
- 수정 비용 (시간)
- 기술적 리스크 (시스템 장애, 데이터 손실 가능성)
- 개선에 의한 시간 삭감 효과
- 추천 실시 시기"
```

### 상세 예

```bash
# 프로젝트 타입의 자동 검출과 분석
find . -maxdepth 2 -type f \( -name "package.json" -o -name "Cargo.toml" -o -name "pubspec.yaml" -o -name "go.mod" -o -name "pom.xml" \)
"검출된 프로젝트 타입에 기반해서, 다음을 분석해줘:
1. 언어・프레임워크 고유의 기술적 부채
2. 베스트 프랙티스로부터의 일탈
3. 모던화의 기회
4. 단계적인 개선 전략"

# 코드의 품질 메트릭스 분석
find . -type f -name "*" | grep -E "\.(js|ts|py|rs|go|dart|kotlin|swift|java)$" | wc -l
"프로젝트의 코드 품질을 분석하고, 다음 메트릭스를 제시해줘:
- 순환 복잡도가 높은 함수
- 중복 코드의 검출
- 너무 긴 파일/함수
- 적절한 에러 핸들링의 결여"

# 보안 부채의 검출
grep -r "password\|secret\|key\|token" . --exclude-dir=.git --exclude-dir=node_modules | grep -v ".env.example"
"보안에 관한 기술적 부채를 검출하고, 수정 우선도와 대책을 제안해줘"

# 테스트 부족의 분석
find . -type f \( -name "*test*" -o -name "*spec*" \) | wc -l && find . -type f -name "*.md" | xargs grep -l "test"
"테스트 커버리지의 기술적 부채를 분석하고, 테스트 전략을 제안해줘"
```

### 부채의 우선순위 매트릭스

```text
우선도 = (영향도 × 발생빈도) ÷ 수정 비용
```

| 우선도                  | 개발에의 영향 | 수정 비용 | 시간 삭감 효과 | 투자 대 효과      | 대응 기한  |
| ----------------------- | ------------- | --------- | -------------- | ----------------- | ---------- |
| **[P0] 지금 당장 대응** | 높음          | 낮음      | > 5배          | 투자 1h→삭감 5h+  | 즉시       |
| **[P1] 이번 주중**      | 높음          | 중간      | 2-5배          | 투자 1h→삭감 2-5h | 1주일 이내 |
| **[P2] 이번 달중**      | 낮음          | 높음      | 1-2배          | 투자 1h→삭감 1-2h | 1개월 이내 |
| **[P3] 분기중**         | 낮음          | 낮음      | < 1배          | 투자=삭감시간     | 3개월 이내 |

### 부채 타입별의 평가 기준

| 부채 타입          | 검출 방법                  | 개발에의 영향                   | 수정 시간 |
| ------------------ | -------------------------- | ------------------------------- | --------- |
| **아키텍처 부채**  | 순환 의존, 밀결합          | 변경시 영향범위 대, 테스트 곤란 | 40-80h    |
| **보안 부채**      | CVE 스캔, OWASP            | 취약성 리스크, 컴플라이언스     | 8-40h     |
| **성능 부채**      | N+1, 메모리 리크           | 응답시간 증가, 리소스 소비      | 16-40h    |
| **테스트 부채**    | 커버리지 < 60%             | 버그 검출 지연, 품질 불안정     | 20-60h    |
| **문서 부채**      | README 부족, API 문서 없음 | 온보딩 시간 증가                | 8-24h     |
| **의존관계 부채**  | 2년 이상 미업데이트        | 보안 리스크, 호환성 문제        | 4-16h     |
| **코드 품질 부채** | 복잡도 > 10                | 이해・수정 시간 증가            | 2-8h      |

### 기술적 부채의 영향도 산출

```text
영향도 = Σ(각 요소의 가중치 × 측정값)

📊 측정 가능한 영향 지표:
├─ 개발 속도에의 영향
│  ├─ 코드 이해 시간: +X% (복잡도에 비례)
│  ├─ 변경시의 영향 범위: Y파일 (결합도로 측정)
│  └─ 테스트 실행 시간: Z분 (CI/CD 파이프라인)
│
├─ 품질에의 영향
│  ├─ 버그 발생률: 복잡도 10마다 +25%
│  ├─ 리뷰 시간: 행수 × 복잡도 계수
│  └─ 테스트 부족 리스크: 커버리지 60% 미만에서 고리스크
│
└─ 팀 효율에의 영향
   ├─ 온보딩 시간: 문서 부족으로 +100%
   ├─ 지식의 속인화: 단일 기여자율 >80%에서 요주의
   └─ 코드 중복에 의한 수정 개소: 중복률 × 변경 빈도
```

### 시간 베이스의 ROI 계산

```text
ROI = (삭감 시간 - 투자 시간) ÷ 투자 시간 × 100

예: 순환 의존의 해소
├─ 투자 시간: 16시간 (리팩터링)
├─ 삭감 효과 (월차):
│  ├─ 컴파일 시간: -10분/일 × 20일 = 200분
│  ├─ 디버그 시간: -2시간/주 × 4주 = 8시간
│  └─ 신기능 추가: -30% 시간 단축 = 12시간
├─ 월차 삭감 시간: 23.3시간
└─ 3개월 ROI: (70 - 16) ÷ 16 × 100 = 337%
```

### 주의사항

- 프로젝트의 언어나 프레임워크를 자동 검출하고, 그에 따른 분석을 실행합니다
- 건전성 스코어는 0-100점으로 평가하고, 70점 이상을 건전, 50점 이하를 요개선으로 합니다
- 시간적 비용과 개선 효과를 구체적으로 산출하고, 데이터에 기반한 의사결정을 지원합니다
- 금전 환산이 필요한 경우는, 팀의 평균 시급이나 프로젝트 고유의 계수를 별도 지정해 주세요