238 lines
7.6 KiB
Plaintext
238 lines
7.6 KiB
Plaintext
---
|
|
description: Code refactoring and technical debt management for AI-assisted development
|
|
globs:
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Rule: Code Refactoring and Technical Debt Management
|
|
|
|
## Goal
|
|
Guide AI in systematic code refactoring to improve maintainability, reduce complexity, and prevent technical debt accumulation in AI-assisted development projects.
|
|
|
|
## When to Apply This Rule
|
|
- Code complexity has increased beyond manageable levels
|
|
- Duplicate code patterns are detected
|
|
- Performance issues are identified
|
|
- New features are difficult to integrate
|
|
- Code review reveals maintainability concerns
|
|
- Weekly technical debt assessment indicates refactoring needs
|
|
|
|
## Pre-Refactoring Assessment
|
|
|
|
Before starting any refactoring, the AI MUST:
|
|
|
|
1. **Context Analysis:**
|
|
- Review existing `CONTEXT.md` for architectural decisions
|
|
- Analyze current code patterns and conventions
|
|
- Identify all files that will be affected (search the codebase for use)
|
|
- Check for existing tests that verify current behavior
|
|
|
|
2. **Scope Definition:**
|
|
- Clearly define what will and will not be changed
|
|
- Identify the specific refactoring pattern to apply
|
|
- Estimate the blast radius of changes
|
|
- Plan rollback strategy if needed
|
|
|
|
3. **Documentation Review:**
|
|
- Check `./docs/` for relevant module documentation
|
|
- Review any existing architectural diagrams
|
|
- Identify dependencies and integration points
|
|
- Note any known constraints or limitations
|
|
|
|
## Refactoring Process
|
|
|
|
### Phase 1: Planning and Safety
|
|
1. **Create Refactoring Plan:**
|
|
- Document the current state and desired end state
|
|
- Break refactoring into small, atomic steps
|
|
- Identify tests that must pass throughout the process
|
|
- Plan verification steps for each change
|
|
|
|
2. **Establish Safety Net:**
|
|
- Ensure comprehensive test coverage exists
|
|
- If tests are missing, create them BEFORE refactoring
|
|
- Document current behavior that must be preserved
|
|
- Create backup of current implementation approach
|
|
|
|
3. **Get Approval:**
|
|
- Present the refactoring plan to the user
|
|
- Wait for explicit "Go" or "Proceed" confirmation
|
|
- Do NOT start refactoring without approval
|
|
|
|
### Phase 2: Incremental Implementation
|
|
4. **One Change at a Time:**
|
|
- Implement ONE refactoring step per iteration
|
|
- Run tests after each step to ensure nothing breaks
|
|
- Update documentation if interfaces change
|
|
- Mark progress in the refactoring plan
|
|
|
|
5. **Verification Protocol:**
|
|
- Run all relevant tests after each change
|
|
- Verify functionality works as expected
|
|
- Check performance hasn't degraded
|
|
- Ensure no new linting or type errors
|
|
|
|
6. **User Checkpoint:**
|
|
- After each significant step, pause for user review
|
|
- Present what was changed and current status
|
|
- Wait for approval before continuing
|
|
- Address any concerns before proceeding
|
|
|
|
### Phase 3: Completion and Documentation
|
|
7. **Final Verification:**
|
|
- Run full test suite to ensure nothing is broken
|
|
- Verify all original functionality is preserved
|
|
- Check that new code follows project conventions
|
|
- Confirm performance is maintained or improved
|
|
|
|
8. **Documentation Update:**
|
|
- Update `CONTEXT.md` with new patterns/decisions
|
|
- Update module documentation in `./docs/`
|
|
- Document any new conventions established
|
|
- Note lessons learned for future refactoring
|
|
|
|
## Common Refactoring Patterns
|
|
|
|
### Extract Method/Function
|
|
```
|
|
WHEN: Functions/methods exceed 50 lines or have multiple responsibilities
|
|
HOW:
|
|
1. Identify logical groupings within the function
|
|
2. Extract each group into a well-named helper function
|
|
3. Ensure each function has a single responsibility
|
|
4. Verify tests still pass
|
|
```
|
|
|
|
### Extract Module/Class
|
|
```
|
|
WHEN: Files exceed 250 lines or handle multiple concerns
|
|
HOW:
|
|
1. Identify cohesive functionality groups
|
|
2. Create new files for each group
|
|
3. Move related functions/classes together
|
|
4. Update imports and dependencies
|
|
5. Verify module boundaries are clean
|
|
```
|
|
|
|
### Eliminate Duplication
|
|
```
|
|
WHEN: Similar code appears in multiple places
|
|
HOW:
|
|
1. Identify the common pattern or functionality
|
|
2. Extract to a shared utility function or module
|
|
3. Update all usage sites to use the shared code
|
|
4. Ensure the abstraction is not over-engineered
|
|
```
|
|
|
|
### Improve Data Structures
|
|
```
|
|
WHEN: Complex nested objects or unclear data flow
|
|
HOW:
|
|
1. Define clear interfaces/types for data structures
|
|
2. Create transformation functions between different representations
|
|
3. Ensure data flow is unidirectional where possible
|
|
4. Add validation at boundaries
|
|
```
|
|
|
|
### Reduce Coupling
|
|
```
|
|
WHEN: Modules are tightly interconnected
|
|
HOW:
|
|
1. Identify dependencies between modules
|
|
2. Extract interfaces for external dependencies
|
|
3. Use dependency injection where appropriate
|
|
4. Ensure modules can be tested in isolation
|
|
```
|
|
|
|
## Quality Gates
|
|
|
|
Every refactoring must pass these gates:
|
|
|
|
### Technical Quality
|
|
- [ ] All existing tests pass
|
|
- [ ] No new linting errors introduced
|
|
- [ ] Code follows established project conventions
|
|
- [ ] No performance regression detected
|
|
- [ ] File sizes remain under 250 lines
|
|
- [ ] Function sizes remain under 50 lines
|
|
|
|
### Maintainability
|
|
- [ ] Code is more readable than before
|
|
- [ ] Duplicated code has been reduced
|
|
- [ ] Module responsibilities are clearer
|
|
- [ ] Dependencies are explicit and minimal
|
|
- [ ] Error handling is consistent
|
|
|
|
### Documentation
|
|
- [ ] Public interfaces are documented
|
|
- [ ] Complex logic has explanatory comments
|
|
- [ ] Architectural decisions are recorded
|
|
- [ ] Examples are provided where helpful
|
|
|
|
## AI Instructions for Refactoring
|
|
|
|
1. **Always ask for permission** before starting any refactoring work
|
|
2. **Start with tests** - ensure comprehensive coverage before changing code
|
|
3. **Work incrementally** - make small changes and verify each step
|
|
4. **Preserve behavior** - functionality must remain exactly the same
|
|
5. **Update documentation** - keep all docs current with changes
|
|
6. **Follow conventions** - maintain consistency with existing codebase
|
|
7. **Stop and ask** if any step fails or produces unexpected results
|
|
8. **Explain changes** - clearly communicate what was changed and why
|
|
|
|
## Anti-Patterns to Avoid
|
|
|
|
### Over-Engineering
|
|
- Don't create abstractions for code that isn't duplicated
|
|
- Avoid complex inheritance hierarchies
|
|
- Don't optimize prematurely
|
|
|
|
### Breaking Changes
|
|
- Never change public APIs without explicit approval
|
|
- Don't remove functionality, even if it seems unused
|
|
- Avoid changing behavior "while we're here"
|
|
|
|
### Scope Creep
|
|
- Stick to the defined refactoring scope
|
|
- Don't add new features during refactoring
|
|
- Resist the urge to "improve" unrelated code
|
|
|
|
## Success Metrics
|
|
|
|
Track these metrics to ensure refactoring effectiveness:
|
|
|
|
### Code Quality
|
|
- Reduced cyclomatic complexity
|
|
- Lower code duplication percentage
|
|
- Improved test coverage
|
|
- Fewer linting violations
|
|
|
|
### Developer Experience
|
|
- Faster time to understand code
|
|
- Easier integration of new features
|
|
- Reduced bug introduction rate
|
|
- Higher developer confidence in changes
|
|
|
|
### Maintainability
|
|
- Clearer module boundaries
|
|
- More predictable behavior
|
|
- Easier debugging and troubleshooting
|
|
- Better performance characteristics
|
|
|
|
## Output Files
|
|
|
|
When refactoring is complete, update:
|
|
- `refactoring-log-[date].md` - Document what was changed and why
|
|
- `CONTEXT.md` - Update with new patterns and decisions
|
|
- `./docs/` - Update relevant module documentation
|
|
- Task lists - Mark refactoring tasks as complete
|
|
|
|
## Final Verification
|
|
|
|
Before marking refactoring complete:
|
|
1. Run full test suite and verify all tests pass
|
|
2. Check that code follows all project conventions
|
|
3. Verify documentation is up to date
|
|
4. Confirm user is satisfied with the results
|
|
5. Record lessons learned for future refactoring efforts
|