Claude Code workflow for large repository refactors

Goal

Refactor high-impact code safely without losing observability.

Recommended execution pattern

1) Start from a scoped spec

Write a short spec in CLAUDE.md with:

• objective
• non-goals
• files in scope
• pass/fail test commands

2) Run proposal mode first

Have Claude Code output:

• implementation plan
• possible edge cases
• migration steps for interfaces

Approve or adjust before any edits.

3) Enforce checkpoint commits

Commit after each meaningful stage:

1. signature/type update
2. implementation update
3. caller migration
4. cleanup and docs

4) Validate continuously

Run narrow tests after each stage, then full targeted suite at the end.

5) Produce release notes

Generate a short migration note for teammates:

• breaking changes
• required follow-ups
• rollback strategy

Best use cases

• service boundary refactors
• API migrations
• dependency replacement

Avoid

• combining migration + feature work in one branch
• accepting unreviewed generated scripts
• skipping final static analysis