Skip to main content
Every codebase accumulates shortcuts, outdated patterns, and architectural drift that slow the team down over time. Refactoring that debt away is critical but rarely gets prioritized because it is high-effort and low-visibility. Blitzy handles the heavy lifting: it restructures code while preserving external behavior, applies modern design patterns, and validates equivalence so your team can modernize confidently instead of indefinitely.

Refactor Template

Use the Refactor Template for general code refactoring with a structured prompt
Jump to: When to Use | Prompt Structure | Key Considerations | Common Patterns | Troubleshooting

​
When to Use This Approach

Clean up rushed implementations and architectural drift that make every change slower and riskier.

​
Prompt Structure

Follow the Golden Rules when writing your refactoring prompt. Focus especially on:
  • Objective Clarity - Specify exact files, line ranges, and target architecture patterns
  • Behavioral Constraints - Define what must remain unchanged (APIs, response formats, performance)
  • Reference Patterns - Point to existing code demonstrating the architectural style to follow
  • Success Metrics - Include measurable targets (performance, test coverage, maintainability)
Destination repository required for new-repo refactors — For refactors that target a new repository (e.g., monolith-to-microservices extraction), the destination repository must already exist on your Git provider before starting the run. Blitzy pushes to existing repositories only — it cannot create new ones. See GitHub Integration or GitHub Enterprise Server Integration for setup details.

​
Key Considerations

Test Coverage Is Mandatory

Establish comprehensive automated tests before refactoring to validate behavioral equivalence. Without tests, you cannot verify the refactored code maintains identical functionality.

Behavioral Constraints Over Structure

Explicitly state what must remain unchanged (API contracts, response formats, performance characteristics) rather than describing how the refactored code should be structured.

Incremental Scope Prevents Risk

Break large refactorings into small, independently testable changes. Attempting to refactor entire subsystems in single PRs creates review bottlenecks and increases bug risk.

Performance Baselines Establish Success

Measure current performance characteristics (latency, throughput, resource usage) before refactoring and define target metrics.

​
Common Patterns

Legacy API modernization - Convert callback-based code to async/await while preserving identical API contracts, error handling, and response formats. Reference recently modernized controllers as patterns. Monolith decomposition - Extract service boundaries from monolithic code, define clear API contracts between services, preserve existing external APIs, and add retry logic for inter-service communication. Design pattern application - Replace ad-hoc implementations with established patterns (Strategy, Factory, Observer), extract pattern-specific classes, and maintain existing public interfaces while improving internal organization.

​
Troubleshooting

Tests may be validating implementation details rather than behavior. Update tests to focus on public interfaces and observable behavior while ensuring refactored code maintains identical outputs.
Benchmark before and after refactoring. Add the Analyze Performance Impact rule to your project on the platform and specify performance targets explicitly (latency, throughput, resource usage).
Add characterization tests before refactoring that capture current behavior, including edge cases. Verify all tests pass identically with refactored code before deployment.
Break into smaller incremental changes. Each refactoring should touch minimal files and be independently deployable. Use feature flags for gradual rollout.
Map all dependencies before refactoring. Verify API contracts remain unchanged. Add integration tests validating interactions with dependent services remain identical.