Claude Code: Refactor command for code quality cleanup with jscpd, knip, and code-simplifier

refactor.md

Refactor

You are doing a focused refactoring session. This is a distinct phase, not continuous activity.

Step 1: Detect Project Type

ls package.json pyproject.toml setup.py 2>/dev/null

---

Step 2: Run Quality Checks

JavaScript/TypeScript

Check if jscpd and knip are installed. If not:

npm install -D jscpd knip
npx knip init

Run both tools:

npx jscpd src/
npx knip

Report the results:

• jscpd: Number of duplicate code blocks and duplication percentage
• knip: Unused files, unused dependencies, unused exports, unused types

Python

Ensure tools are installed:

pip install ruff vulture  # or: uv pip install ruff vulture

Run quality checks:

# Unused imports, variables, redefinitions
ruff check src/ --select=F401,F841,F811 --statistics

# Dead code detection
vulture src/ --min-confidence 80

# Auto-fix what's possible
ruff check src/ --select=F401,F841,F811 --fix

Report the results:

• ruff: Unused imports (F401), unused variables (F841), redefinitions (F811)
• vulture: Dead functions, classes, and variables

---

Step 3: Fix Issues Found

For each issue:

• Duplicate code: Extract to shared utility or module
• Unused files: Delete them
• Unused dependencies: Remove from package.json or pyproject.toml
• Unused exports/imports: Remove the export or delete if truly unused
• Dead functions/classes: Delete if no longer needed

Step 4: Run Code Simplifier

After fixing quality issues, run the code-simplifier agent to simplify complex patterns:

Use the Task tool with subagent_type="code-simplifier"

This simplifies complex code patterns that accumulated during development.

Step 5: Delete Obsolete Files

Look for files that are no longer needed after recent changes. Common culprits:

• Old implementations that were replaced
• Test files for deleted code
• Unused components or utilities
• Stale documentation
• Prototype files superseded by production versions

Step 6: Verify Tests Pass

# JavaScript
npm test

# Python
pytest tests/ -v --tb=short

Step 7: Commit Cleanup

Commit the refactoring changes as a distinct commit:

git add -A
git commit -m "refactor: code quality cleanup (dead code removal, lint fixes)"

---

Guidelines

• Treat refactoring as a distinct phase, not continuous activity
• Do this when you feel pain from Claude making mistakes, or after large additions
• ~20% of dev time on focused code quality improvements is reasonable
• Don't over-optimize—ship working code, then clean up
• Always run tests after cleanup to catch broken imports