Refactoring Best Practices

Enforce TDD/BDD practices to refactor code without changing behavior.

Updated Oct 31, 2025
One-click install
npx skills add https://github.com/RomualdP/hoki --skill refactoring-best-practices
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: Refactoring Best Practices
Source: https://github.com/RomualdP/hoki/tree/main/.claude/skills/refactoring
Command: npx skills add https://github.com/RomualdP/hoki --skill refactoring-best-practices

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires jest.

What problem does it solve?

This Skill provides a safe and systematic methodology for refactoring code, ensuring that improvements to code structure do not alter existing behavior, are guided by tests, and are performed in small, incremental steps to maintain code quality and prevent regressions.

Core Features & Use Cases

  • TDD Cycle (Red-Green-Refactor): Emphasizes writing failing tests, then minimal code to pass, and finally refactoring while keeping tests green.
  • BDD/AAA Testing Patterns: Guides on structuring tests using Given-When-Then (BDD) for user scenarios and Arrange-Act-Assert (AAA) for unit tests.
  • Common Refactoring Patterns: Provides practical examples for "Extract Function," "Extract Component," "Remove Duplication," and "Simplify Nested Structures."
  • Use Case: When encountering a long, complex function with duplicated logic, use this Skill to first ensure existing tests pass, then apply "Extract Function" and "Remove Duplication" patterns in small, tested steps, ensuring the function's behavior remains unchanged.

Quick Start

Before refactoring, ensure all existing tests pass. Then, identify a "code smell" (e.g., a long function). Write a failing test for the new behavior you want to enable, implement minimal code to pass, and then refactor the code while keeping all tests green.

Frequently Asked Questions about Refactoring Best Practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I refactor code without breaking existing functionality?

Refactoring safely requires a test-driven approach: ensure all existing tests pass first, then write failing tests for new behavior, implement minimal code to pass those tests, and refactor while keeping all tests green. This RED-GREEN-REFACTOR cycle prevents behavior changes.

What's the best way to extract a function from duplicated code?

Use the Extract Function pattern within the RED-GREEN-REFACTOR cycle. Write tests that cover the duplicated logic, identify the common behavior, extract it into a separate function, and verify all tests still pass after each small change.

How do I structure tests when refactoring with TDD?

Use Arrange-Act-Assert (AAA) for unit tests or Given-When-Then (BDD) for user scenarios. AAA organizes setup, execution, and verification; BDD frames behavior in user-centered language. Both patterns work with jest to validate refactored code.

Can I refactor nested structures and complex functions incrementally?

Yes. The Simplify Nested Structures and Remove Duplication patterns apply the RED-GREEN-REFACTOR cycle to break down long functions into smaller, testable pieces. Each refactoring step stays validated by tests.

When should I refactor versus rewriting code?

Refactor when behavior must remain unchanged but structure improves. If tests pass before and after, refactoring preserves correctness. Rewriting is riskier; refactoring with TDD/BDD ensures quality and prevents regressions across unit, integration, and frontend/backend scenarios.

What code smells signal that refactoring is needed?

Long functions, duplicated logic, nested complexity, and unclear naming are common code smells. Identify them first, then apply refactoring patterns like Extract Function, Remove Duplication, or Simplify Nested Structures while tests validate the unchanged behavior.