Claude Code로 기술 부채를 시각화하고 체계적으로 줄이는 방법

“리팩터링하고 싶지만 시간이 없어요.” “어디서부터 시작해야 할까요?” 기술 부채는 조용히 쌓여갑니다. Claude Code를 사용하면 평소 비용의 일부만으로 부채를 체계적으로 드러내고, 우선순위를 정하고, 상환할 수 있습니다.

1. 코드베이스 전반의 코드 스멜 감지

전체 스캔부터 시작하세요.

claude -p "
src/를 스캔해서 코드 스멜을 찾아주세요. 확인 항목:

- 50줄이 넘는 함수
- 깊은 중첩(4단계 이상)
- 중복된 로직
- God Class(과도한 책임)
- 매직 넘버
- 사용되지 않는 export
- any 타입 사용
- TODO / FIXME 주석

docs/tech-debt/smells.md에 다음 형식으로 출력하세요:
| File | Line | Smell | Severity(1-5) | Suggested fix |
"

심각도별로 정렬된 목록이 출발점이 됩니다.

2. 의존성 부채 측정

오래된 라이브러리와 취약점도 부채입니다.

claude -p "
package.json과 함께 npm audit, npm outdated를 분석해주세요:

1. 메이저 업데이트가 필요한 라이브러리
2. 알려진 취약점
3. 유지보수가 중단된 패키지
4. 중복(예: moment + date-fns 혼용)

docs/tech-debt/dependencies.md에 현재 버전, 최신 버전, 브레이킹 체인지, 업데이트 우선순위를 표 형식으로 출력하세요.
"

3. ICE Score로 우선순위 정하기

모든 것을 고칠 수는 없습니다. Impact × Confidence × Ease로 순위를 매기세요.

claude -p "
docs/tech-debt/smells.md와 dependencies.md를 사용해 각 항목에 점수를 매겨주세요:

- Impact (I): 비즈니스/개발 속도에 미치는 영향 (1-10)
- Confidence (C): 영향의 확실성 (1-10)
- Ease (E): 수정 난이도 (1-10)

Score = I × C × E 내림차순으로 정렬하세요.
docs/tech-debt/backlog.md로 출력하세요.
상위 10개에 대해 예상 인일(person-days)을 포함하세요.
"

수치 점수는 프로덕트 매니저에게 설득력 있는 근거가 됩니다.

4. 작은 상환 PR 자동 생성

상환을 리뷰 가능한 PR로 나누세요.

claude -p "
docs/tech-debt/backlog.md의 #1 항목에 대해:

1. 브랜치 생성: refactor/tech-debt-001
2. 해당 문제만 수정 (동작 변경 없음)
3. 기존 테스트가 통과하는지 확인
4. 크기가 크면 여러 커밋으로 분할
5. gh pr create 실행

PR 본문에 다음을 포함하세요:
- 어떤 부채였는지
- 왜 지금 상환하는지
- ICE 점수
- 다른 코드에 미치는 영향 범위
"

5. 테스트되지 않은 핫스팟 식별

커버리지가 낮은 영역은 미래의 부채가 됩니다.

npm test -- --coverage --coverageReporters=json

claude -p "
coverage/coverage-summary.json을 분석해주세요:

- 커버리지 50% 미만 파일
- 그중 비즈니스 로직이 포함된 파일
- 테스트 추가 우선순위

docs/tech-debt/coverage-gaps.md에 출력하세요.
상위 3개 파일에 대해 테스트 케이스를 제안해주세요.
"

테스트 자동 생성과 결합하면 효과가 배가됩니다.

6. 주간 리포트로 상환을 가시화

가시성이 없으면 팀은 포기합니다.

claude -p "
지난 한 주간의 기술 부채 상환 상황을 보고해주세요:

- 해결된 항목 (docs/tech-debt/backlog.md 확인)
- 새로 발견된 부채
- 여전히 열려 있는 심각도 5 항목
- 의존성 업데이트 진행 상황

docs/tech-debt/weekly-report-$(date +%Y-%m-%d).md에 출력하세요.
5분짜리 스탠드업 낭독에 맞게 조정해주세요.
"

월요일 아침에 cron으로 실행하여 상환을 제도화하세요.

7. 새로운 부채를 입구에서 차단

유입이 계속되면 상환은 무의미합니다. CLAUDE.md에 규칙을 코드화하세요.

## 새로운 기술 부채 방지 규칙

### 금지 사항
- 새로운 any 타입 값 (불가피할 경우 이유를 명시한 // @ts-expect-error 사용)
- TODO 없는 임시 방편 로직
- 테스트 없는 비즈니스 로직

### PR 체크리스트
- [ ] 새 코드 커버리지 ≥ 80%
- [ ] ESLint 에러 0건
- [ ] 의존성 추가는 PR에서 정당화

### 허용 가능한 예외
- 핫픽스 (후속 티켓 포함)
- POC 코드 (프로덕션 전 재작성 필수)

pre-commit 훅으로 강제하세요. Hooks 가이드 참조.

안티 패턴

❌ 거대한 리팩터 PR 하나

“전부 고치기” PR은 리뷰가 불가능합니다. 스멜 하나 = PR 하나.

❌ 동작 변경 혼합

같은 PR에 기능 작업과 리팩터링을 절대 섞지 마세요. 리뷰 부담이 두 배가 됩니다.

❌ 테스트 없는 리팩터링

커버리지가 낮다면 먼저 테스트를 작성한 뒤 리팩터링하세요. 안전망이 없으면 새로운 버그가 생깁니다.

결론

• Claude Code로 스멜, 의존성 부채, 커버리지 갭을 드러내세요
• ICE 스코어링으로 우선순위를 수치화하세요
• 상환을 작은 PR로 나누세요
• 주간 진행 리포트를 발행하세요
• CLAUDE.md 규칙으로 새 부채를 차단하세요
• 스멜 하나 = PR 하나

기술 부채는 “언젠가” 고칠 것이 아닙니다. 매주 조금씩 갚아야 할 것입니다. Claude Code는 그 리듬의 비용을 크게 낮춰줍니다.

관련 글: 리팩터링 자동화 / 레거시 코드 현대화 / 코드 리뷰 체크리스트

공식 문서: Anthropic Claude Code