playbooks

home / skills / pproenca / dot-skills / refactor

refactor skill

/skills/.curated/refactor

This skill guides automated code refactoring using Fowler and Clean Code principles to improve maintainability and readability.

npx playbooks add skill pproenca/dot-skills --skill refactor

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

Files (49)
SKILL.md
4.8 KB
---
name: refactor
description: Code refactoring best practices based on Martin Fowler's catalog and Clean Code principles (formerly refactoring). This skill should be used when refactoring existing code, improving code structure, reducing complexity, eliminating code smells, or reviewing code for maintainability. Triggers on tasks involving extract method, rename, decompose conditional, reduce coupling, or improve readability.
---

# Fowler/Martin Code Refactoring Best Practices

Comprehensive code refactoring guide based on Martin Fowler's catalog and Clean Code principles, designed for AI agents and LLMs. Contains 43 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

## When to Apply

Reference these guidelines when:
- Refactoring existing code to improve maintainability
- Decomposing long methods or large classes
- Reducing coupling between components
- Simplifying complex conditional logic
- Reviewing code for code smells and anti-patterns

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Structure & Decomposition | CRITICAL | `struct-` |
| 2 | Coupling & Dependencies | CRITICAL | `couple-` |
| 3 | Naming & Clarity | HIGH | `name-` |
| 4 | Conditional Logic | HIGH | `cond-` |
| 5 | Abstraction & Patterns | MEDIUM-HIGH | `pattern-` |
| 6 | Data Organization | MEDIUM | `data-` |
| 7 | Error Handling | MEDIUM | `error-` |
| 8 | Micro-Refactoring | LOW | `micro-` |

## Quick Reference

### 1. Structure & Decomposition (CRITICAL)

- `struct-extract-method` - Extract Method for Long Functions
- `struct-single-responsibility` - Apply Single Responsibility Principle
- `struct-extract-class` - Extract Class from Large Class
- `struct-compose-method` - Compose Method for Readable Flow
- `struct-function-length` - Keep Functions Under 20 Lines
- `struct-replace-method-with-object` - Replace Method with Method Object
- `struct-parameter-object` - Introduce Parameter Object

### 2. Coupling & Dependencies (CRITICAL)

- `couple-dependency-injection` - Use Dependency Injection
- `couple-hide-delegate` - Hide Delegate to Reduce Coupling
- `couple-remove-middle-man` - Remove Middle Man When Excessive
- `couple-feature-envy` - Fix Feature Envy by Moving Methods
- `couple-interface-segregation` - Apply Interface Segregation Principle
- `couple-preserve-whole-object` - Preserve Whole Object Instead of Fields

### 3. Naming & Clarity (HIGH)

- `name-intention-revealing` - Use Intention-Revealing Names
- `name-avoid-abbreviations` - Avoid Abbreviations and Acronyms
- `name-consistent-vocabulary` - Use Consistent Vocabulary
- `name-searchable-names` - Use Searchable Names
- `name-avoid-encodings` - Avoid Type Encodings in Names

### 4. Conditional Logic (HIGH)

- `cond-guard-clauses` - Replace Nested Conditionals with Guard Clauses
- `cond-polymorphism` - Replace Conditional with Polymorphism
- `cond-decompose` - Decompose Complex Conditionals
- `cond-consolidate` - Consolidate Duplicate Conditional Fragments
- `cond-special-case` - Introduce Special Case Object
- `cond-lookup-table` - Replace Conditional with Lookup Table

### 5. Abstraction & Patterns (MEDIUM-HIGH)

- `pattern-strategy` - Extract Strategy for Algorithm Variants
- `pattern-template-method` - Use Template Method for Shared Skeleton
- `pattern-factory` - Use Factory for Complex Object Creation
- `pattern-open-closed` - Apply Open-Closed Principle
- `pattern-composition-over-inheritance` - Prefer Composition Over Inheritance
- `pattern-extract-superclass` - Extract Superclass for Common Behavior

### 6. Data Organization (MEDIUM)

- `data-encapsulate-collection` - Encapsulate Collection
- `data-replace-primitive` - Replace Primitive with Object
- `data-encapsulate-record` - Encapsulate Record into Class
- `data-split-variable` - Split Variable with Multiple Assignments
- `data-replace-temp-with-query` - Replace Temp with Query

### 7. Error Handling (MEDIUM)

- `error-exceptions-over-codes` - Use Exceptions Instead of Error Codes
- `error-custom-exceptions` - Create Domain-Specific Exception Types
- `error-fail-fast` - Fail Fast with Preconditions
- `error-separate-concerns` - Separate Error Handling from Business Logic

### 8. Micro-Refactoring (LOW)

- `micro-remove-dead-code` - Remove Dead Code
- `micro-inline-variable` - Inline Trivial Variables
- `micro-simplify-expressions` - Simplify Boolean Expressions
- `micro-rename-for-clarity` - Rename for Clarity

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules
- Individual rules: `references/{prefix}-{slug}.md`

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

Overview

This skill provides practical refactoring guidance derived from Martin Fowler’s catalog and Clean Code principles. It targets common refactoring operations like extract method, rename, decompose conditional, and reducing coupling. Use it to improve code structure, readability, and maintainability while minimizing risk during change.

How this skill works

The skill inspects code structure, identifies code smells, and recommends prioritized refactor actions across eight categories: structure, coupling, naming, conditionals, abstraction, data, error handling, and micro-refactors. It maps triggers (extract method, rename, decompose conditional, etc.) to concrete patterns and step-by-step tactics, and suggests safe heuristics such as keeping functions short and applying single-responsibility. Recommendations emphasize minimal, test-backed changes and appropriate abstraction choices.

When to use it

  • Refactoring long or complex functions into smaller units
  • Reducing coupling between modules or hiding delegates
  • Improving unclear names and domain vocabulary
  • Simplifying nested conditionals or replacing them with polymorphism
  • Breaking up large classes or extracting parameter objects

Best practices

  • Prioritize structural and coupling fixes first — they yield the largest maintainability gains
  • Keep functions short (aim < 20 lines) and give them intention-revealing names
  • Use tests or automated checks before and after refactors to detect behavioral changes
  • Prefer composition and dependency injection to reduce tight coupling
  • Apply small, reversible micro-refactors frequently rather than large sweeping changes

Example use cases

  • Extract a long method into smaller, well-named helper methods to clarify intent
  • Replace a switch/if-else chain with strategy or polymorphism for easier extension
  • Introduce a parameter object when many related parameters are passed together
  • Refactor a god-class by extracting cohesive responsibilities into new classes
  • Rename variables and methods to a consistent, searchable vocabulary to reduce cognitive load

FAQ

Will these refactors change program behavior?

Refactors aim to preserve behavior; always run tests before and after. Prefer small, reversible steps and add tests where coverage is missing.

Which refactor should I choose first?

Start with high-impact structural and coupling changes (extract method, single responsibility, dependency injection), then address naming and conditional simplifications.

How do I avoid over-engineering when applying patterns?

Favor the simplest change that solves the immediate problem. Introduce patterns like strategy or factory only when multiple implementations or complexity justify them.