skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
luckys/agent-skills53 installs

refactoring-best-practices

Use when changing existing structure without changing behavior, adding characterization tests, isolating hard dependencies, consolidating APIs, migrating callers, introducing value objects or domain events, replacing null/string/generic exceptions with typed failure contracts, or removing legacy paths safely. Applies to protected incremental change, not an unverified rewrite or unrelated cleanup.

How do I install this agent skill?

npx skills add https://github.com/luckys/agent-skills --skill refactoring-best-practices
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides comprehensive guidance and best practices for safe code refactoring, drawing from established engineering principles and trusted community sources. No malicious patterns or security risks were detected.

  • Socketpass

    No alerts

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

Refactoring Best Practices

Use this skill when the main challenge is changing existing code safely.

Working Style

  1. Protect behavior before improving design.
  2. Prefer small reversible moves over dramatic rewrites.
  3. Add feedback before adding abstraction.
  4. Change one responsibility at a time.
  5. Let the current pain point decide the next move.

Safe Refactoring Workflow

  1. Observe current behavior.

    • Identify outputs, side effects, and error paths.
    • Identify what must not change.
  2. Add feedback.

    • Prefer characterization tests around visible behavior.
    • Add logs or temporary probes only when tests are not enough.
  3. Find a seam.

    • Isolate time, file system, network, framework globals, singletons, and external APIs.
    • Create the narrowest possible boundary around the risky dependency.
  4. Choose the next move.

    • extract method
    • extract class
    • introduce value object
    • introduce first-class collection
    • move method
    • replace conditional with polymorphism
    • separate construction from behavior
    • extract a Domain Event and one secondary subscriber
  5. Re-run feedback after every meaningful step.

High-Value Refactoring Moves

  • Replace a cohesive domain parameter group with a Value Object; use a Parameter Object when the group has no shared domain meaning or invariant.
  • Break large services into role-focused collaborators.
  • Move business rules out of controllers, scripts, and utility classes.
  • Replace type codes and unstable conditionals with explicit roles.
  • Wrap infrastructure behind ports or adapters.
  • Split classes when different method clusters change for different reasons.

Red Flags

  • Big-bang rewrites.
  • New abstractions without a protected behavior baseline.
  • Splitting code into tiny classes without a clearer model.
  • Introducing inheritance only to make tests easier.
  • Refactoring based on aesthetics alone while ignoring risk.

Decision Rules

Refactor now when

  • the same knowledge is duplicated in multiple places
  • the code is blocking a real change
  • the next feature would deepen coupling or duplication
  • the current structure makes defects likely

Wait when

  • there is no feedback loop yet
  • the pain is hypothetical
  • the abstraction is not yet stable enough to deserve a new type
  • the change is broad but the understanding is still weak

References

  • Read references/compatibility-and-migration.md when changing callers, deleting legacy paths, or migrating persisted representations.

  • Read references/safe-change-workflow.md for seam-based refactoring guidance, sensing and separation, and the legacy code change algorithm.

  • Read references/refactoring-moves.md for tactical moves, including the incremental Value Object migration sequence, and when to use them.

  • Read references/code-smells.md when recognizing a problem, using temporal co-change as design evidence, and choosing the right move.

  • Read references/legacy-code-techniques.md for Sprout, Wrap, Extract and Override, and other techniques for working without tests.

  • Read references/characterization-tests.md for how to write tests before refactoring untested code.

  • Read references/domain-event-migration.md for incrementally moving legacy side effects to events/subscribers, preserving failure semantics, durable handoff, and CDC as a migration bridge.

  • Read references/error-contract-migration.md for safely replacing nulls, strings, and generic exceptions while preserving failure timing, diagnostics, redaction, and public contracts.

  • Read references/fran-iglesias-refactoring-guidance.md for practical refactoring heuristics distilled from Fran Iglesias.

  • Read references/language-examples.md for before/after style examples in multiple languages.

Related Skills

  • Use oop-best-practices for everyday new code decisions.
  • Use design-patterns-best-practices when the main issue is choosing an object collaboration pattern.
  • Use ddd-best-practices when moving invariants, splitting a God Aggregate, introducing a root, changing a consistency boundary, or shaping a domain Repository extracted from legacy persistence.
  • Use data-migration-best-practices for moving or backfilling persisted data; this skill owns only the safe code seams and compatibility paths around that operational migration.

Source Influences

This skill is synthesized from ideas emphasized in:

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/luckys/agent-skills/refactoring-best-practices">View refactoring-best-practices on skillZs</a>