How to Visualize and Systematically Reduce Tech Debt with Claude Code

“We want to refactor but never have time.” “Where do we even start?” Tech debt compounds silently. With Claude Code, you can surface, prioritize, and repay debt systematically at a fraction of the usual cost.

1. Detect Code Smells Across the Codebase

Start with a full sweep.

claude -p "
Scan src/ for code smells. Check:

- Functions over 50 lines
- Deep nesting (4+ levels)
- Duplicated logic
- God Classes (overloaded responsibilities)
- Magic numbers
- Unused exports
- any type usage
- TODO / FIXME comments

Output to docs/tech-debt/smells.md as:
| File | Line | Smell | Severity(1-5) | Suggested fix |
"

Severity-ranked inventory becomes your starting point.

2. Measure Dependency Debt

Outdated libraries and vulnerabilities are debt too.

claude -p "
Analyze package.json plus npm audit and npm outdated:

1. Libraries needing major updates
2. Known vulnerabilities
3. Unmaintained packages
4. Duplicates (e.g., moment + date-fns mixed)

Output to docs/tech-debt/dependencies.md with current version, latest, breaking changes, update priority — as a table.
"

3. Prioritize with ICE Scores

You can’t fix everything. Rank by Impact × Confidence × Ease.

claude -p "
Using docs/tech-debt/smells.md and dependencies.md, score each item:

- Impact (I): effect on business/dev velocity (1-10)
- Confidence (C): certainty of impact (1-10)
- Ease (E): effort to fix (1-10)

Sort by Score = I × C × E descending.
Output as docs/tech-debt/backlog.md.
Include estimated person-days for the top 10.
"

Numeric scores make the case to product managers clear.

4. Auto-Generate Small Repayment PRs

Break repayment into reviewable PRs.

claude -p "
For the #1 item in docs/tech-debt/backlog.md:

1. Create branch: refactor/tech-debt-001
2. Fix only that issue (no behavior change)
3. Verify existing tests pass
4. Split into multiple commits if large
5. Run gh pr create

PR body should include:
- What the debt was
- Why repay it now
- ICE score
- Blast radius on other code
"

5. Identify Untested Hot Spots

Low-coverage areas become future debt.

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

claude -p "
Analyze coverage/coverage-summary.json:

- Files under 50% coverage
- Of those, which contain business logic
- Priority for adding tests

Output to docs/tech-debt/coverage-gaps.md.
Propose test cases for the top 3 files.
"

Combine with Test Auto-Generation for compounding impact.

6. Make Repayment Visible with Weekly Reports

Without visibility, teams give up.

claude -p "
Report on tech debt repayment over the past week:

- Items resolved (check docs/tech-debt/backlog.md)
- New debt discovered
- Severity-5 items still open
- Dependency update progress

Output to docs/tech-debt/weekly-report-$(date +%Y-%m-%d).md.
Tune for a 5-minute standup readout.
"

Cron it Monday mornings to institutionalize repayment.

7. Stop New Debt at the Gate

Repayment is hollow if inflow continues. Codify rules in CLAUDE.md.

## Rules to Prevent New Tech Debt

### Forbidden
- New any-typed values (use // @ts-expect-error with reason if unavoidable)
- Stopgap logic without a TODO
- Business logic without tests

### PR Checklist
- [ ] New code coverage ≥ 80%
- [ ] Zero ESLint errors
- [ ] Dependency additions justified in PR

### Acceptable Exceptions
- Hotfixes (with follow-up ticket)
- POC code (must be rewritten before production)

Enforce via pre-commit hooks. See Hooks Guide.

Anti-Patterns

❌ One Giant Refactor PR

“Fix everything” PRs are unreviewable. One smell = one PR.

❌ Mixing Behavior Changes

Never combine feature work with refactoring in the same PR. Review burden doubles.

❌ Refactoring Without Tests

If coverage is low, write tests first, then refactor. No safety net means new bugs.

Conclusion

• Use Claude Code to surface smells, dependency debt, and coverage gaps
• Quantify priority with ICE scoring
• Break repayment into small PRs
• Publish weekly progress reports
• Gate new debt via CLAUDE.md rules
• One smell = one PR

Tech debt isn’t something to fix “someday.” It’s something to repay a little every week. Claude Code collapses the cost of that cadence.

Related: Refactoring Automation / Legacy Code Modernization / Code Review Checklist

Official docs: Anthropic Claude Code