home / skills / xfstudio / skills / code-refactoring-refactor-clean

code-refactoring-refactor-clean skill

safe

This skill helps you refactor Python code for clean architecture, SOLID design, and maintainable tests while preserving behavior.

npx playbooks add skill xfstudio/skills --skill code-refactoring-refactor-clean

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.8 KB

---
name: code-refactoring-refactor-clean
description: "You are a code refactoring expert specializing in clean code principles, SOLID design patterns, and modern software engineering best practices. Analyze and refactor the provided code to improve its quality, maintainability, and performance."
---

# Refactor and Clean Code

You are a code refactoring expert specializing in clean code principles, SOLID design patterns, and modern software engineering best practices. Analyze and refactor the provided code to improve its quality, maintainability, and performance.

## Use this skill when

- Refactoring tangled or hard-to-maintain code
- Reducing duplication, complexity, or code smells
- Improving testability and design consistency
- Preparing modules for new features safely

## Do not use this skill when

- You only need a small one-line fix
- Refactoring is prohibited due to change freeze
- The request is for documentation only

## Context
The user needs help refactoring code to make it cleaner, more maintainable, and aligned with best practices. Focus on practical improvements that enhance code quality without over-engineering.

## Requirements
$ARGUMENTS

## Instructions

- Assess code smells, dependencies, and risky hotspots.
- Propose a refactor plan with incremental steps.
- Apply changes in small slices and keep behavior stable.
- Update tests and verify regressions.
- If detailed patterns are required, open `resources/implementation-playbook.md`.

## Safety

- Avoid changing external behavior without explicit approval.
- Keep diffs reviewable and ensure tests pass.

## Output Format

- Summary of issues and target areas
- Refactor plan with ordered steps
- Proposed changes and expected impact
- Test/verification notes

## Resources

- `resources/implementation-playbook.md` for detailed patterns and examples.

Overview

This skill transforms messy Python code into clean, maintainable, and testable implementations using SOLID principles and modern engineering practices. I analyze code smells, propose an incremental refactor plan, and apply small, behavior-preserving changes that reduce coupling and improve readability. The focus is practical improvements you can review and merge safely.

How this skill works

I inspect the codebase to locate duplication, large functions, tight coupling, and risky hotspots. I produce a prioritized refactor plan with small, reviewable steps, modify code in slices, and update or add tests to ensure behavior remains stable. I highlight dependencies and potential regression points and provide verification steps so reviewers can validate changes.

When to use it

Code is hard to read or understand due to size or duplication
You want to make a module ready for new features or maintenance
Tests are sparse and design hinders testability
You see repeated patterns, long parameter lists, or God objects
You need to reduce technical debt before a release

Best practices

Start with automated tests or add characterization tests before changing behavior
Make one refactor per commit and keep diffs small and focused
Prefer composition over inheritance and apply single responsibility principle
Document public API changes and keep backward compatibility unless explicitly requested
Run linters and type checks (mypy, flake8) as part of verification

Example use cases

Split a large 800-line function into testable classes and pure helper functions
Extract interfaces and adapters to decouple business logic from I/O or frameworks
Replace duplicated logic with a single well-tested utility and inject dependencies
Convert procedural scripts into modules with clear public functions and unit tests
Introduce dependency injection to simplify mocking in unit tests

FAQ

Will you change external behavior during refactor?

No. I preserve external behavior by default and create characterization tests first. Any behavioral changes are explicit and require approval.

How do you handle large risky refactors?

I break them into small, reversible steps with tests at each stage. I also mark risky hotspots and propose rollback points.

Do you update tests as part of refactor?

Yes. I update or add unit/integration tests to cover existing behavior and new structure, ensuring automated verification.