debt-collector

기술 부채 수집기 (Debt Collector)

코드베이스에 산재한 임시 방편(Workaround), 미완성 구현, 품질 타협 지점을 자동으로 탐지하여 기술 부채 기록부(.claude/tech-debt-registry.md)에 체계적으로 등록한다.

담당 에이전트: lead-developer (리드 개발자)

왜 필요한가

기술 부채는 의식적으로 기록하지 않으면 코드 곳곳에 숨어서 복리로 증가한다. // TODO: 나중에 고치기라고 쓴 코드는 대부분 "나중"이 오지 않는다. Debt Collector는 이 숨겨진 부채를 수면 위로 끌어올려 관리 가능하게 만든다.

실행 절차

Step 1: 코드 스캔 — 마커 기반 탐지

코드베이스에서 기술 부채를 나타내는 마커를 검색한다:

탐지 마커 목록:

마커	의미	심각도 기본값
TODO	미완성 구현	Medium
FIXME	알려진 버그/문제	High
HACK	임시 방편, 우회 코드	High
WORKAROUND	외부 제약으로 인한 우회	Medium
XXX	주의 필요한 코드	Medium
TEMP / TEMPORARY	임시 코드	Medium
DEPRECATED (미사용 중인 코드)	제거 예정	Low
@ts-ignore / @ts-expect-error	타입 체크 우회	Medium
# type: ignore (Python)	타입 체크 우회	Medium
eslint-disable	린트 규칙 우회	Low~Medium
noinspection	정적 분석 무시	Low~Medium

Step 2: 코드 스캔 — 패턴 기반 탐지

마커 외에도 코드 패턴으로 부채를 감지한다:

1. 매직 넘버 — 의미 없는 숫자/문자열 상수가 코드에 직접 사용
2. 과도한 복잡도 — 단일 함수 50줄 이상, 중첩 3레벨 이상
3. 중복 코드 — 유사한 코드 블록 반복
4. 빈 catch 블록 — 에러를 삼키는 코드
5. 미사용 코드 — import 되지만 사용되지 않는 모듈/변수
6. 하드코딩된 설정 — 환경별로 달라야 할 값이 코드에 직접
7. 과도한 any 타입 (TypeScript) — 타입 안전성 포기
8. 테스트 없는 핵심 로직 — 테스트 커버리지 사각지대

Step 3: 분류 및 심각도 판정

발견된 부채를 분류하고 심각도를 판정한다:

부채 유형:

유형	설명	예시
설계 부채	아키텍처/설계 타협	God class, 순환 의존성
코드 부채	코드 품질 타협	중복, 매직 넘버, 과도한 복잡도
테스트 부채	테스트 부족	핵심 로직 미테스트, flaky 테스트
문서 부채	문서화 부족	공개 API 문서 없음, 변경 미반영
인프라 부채	인프라 타협	수동 배포, 모니터링 미설정
의존성 부채	오래된 의존성	메이저 버전 2+ 뒤처진 패키지

심각도 판정 기준:

심각도	기준	상환 권장 시점
Critical	보안 취약점, 데이터 유실 위험	즉시
High	버그 발생 가능성 높음, 확장성 차단	다음 스프린트
Medium	유지보수 비용 증가, 개발 속도 저하	2~3 스프린트 내
Low	코드 미관, 사소한 개선	여유 시

Step 4: 기술 부채 기록부 자동 등록

발견된 부채를 .claude/tech-debt-registry.md에 등록한다:

### TD-NNN: [마커에서 추출한 설명]

| 항목 | 내용 |
|------|------|
| ID | TD-NNN |
| 발생 Phase | Phase 5 (구현) |
| 발생일 | YYYY-MM-DD |
| 심각도 | High |
| 유형 | 코드 부채 |
| 설명 | [마커 주석 내용] |
| 파일 위치 | `src/services/auth.ts:42` |
| 타협 이유 | [주석에서 추론 또는 "확인 필요"] |
| 영향 | [자동 판단 또는 "분석 필요"] |
| 상환 방법 | [자동 제안 또는 "검토 필요"] |
| 예상 비용 | [자동 추정 또는 "미정"] |
| 상태 | 미상환 |

Step 5: 스캔 리포트 생성

전체 스캔 결과를 요약한다:

# Debt Collection Report — YYYY-MM-DD

## 요약
| 지표 | 값 |
|------|-----|
| 스캔 파일 수 | N |
| 발견된 부채 | N건 |
| 신규 등록 | N건 |
| 이미 등록됨 (중복) | N건 |
| 심각도별 | Critical: N / High: N / Medium: N / Low: N |

## 트렌드
| 지표 | 이전 스캔 | 이번 스캔 | 변화 |
|------|----------|----------|------|
| 총 부채 건수 | | | ↑/↓/→ |
| Critical+High | | | ↑/↓/→ |
| 상환된 부채 | | | |
| 신규 부채 | | | |

## 상환 우선순위 Top 5
(비즈니스 임팩트 기준 정렬)

Step 6: 산출물

• .claude/tech-debt-registry.md 업데이트 — 신규 부채 항목 추가
• 스캔 리포트 — 실행 결과 요약
• lifecycle.md — 부채 스캔 이력 기록

트리거 시점

• Phase 5 (구현) 완료 후 — 구현 중 발생한 부채 수집
• Phase 7 (QA) 진입 전 — 릴리즈 전 부채 현황 파악
• Phase 8 (운영/회고) 정기 리뷰 — 부채 트렌드 추적
• 대규모 기능 구현 후 — 급하게 구현한 부분 점검
• 정기 스캔 (2주 또는 스프린트 단위)

가이드라인

• 부채 발견 ≠ 비난 — 의식적 부채(Deliberate Debt)는 합리적 판단의 결과일 수 있다
• 발견된 부채를 모두 당장 상환할 필요는 없다 — 우선순위를 정하고 계획적으로
• Critical/High는 빠르게, Medium/Low는 계획적으로 상환
• 매 스프린트 전체 작업의 10-20%를 부채 상환에 할당 (권장)
• TODO에 기한과 담당자를 명시하면 방치 가능성이 줄어든다: // TODO(shaul, 2024-12): 캐시 로직 개선
• 부채가 빠르게 증가하면 근본 원인을 파악한다 (일정 압박? 설계 미비? 역량 부족?)