Skip to content
Back to skills

Refactor

ASecurity

Code refactoring methodology — systematic code transformation patterns, tool selection strategies, and behavior-preserving techniques

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
ai-agentsgobashnodedebuggingrefactoringgitapidocumentation

Works with

  • api

Security analysis

A100/100

Pro scans all 2 files and shows the line behind each finding

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill refactor --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Refactor?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Refactor
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-refactor/badge)](https://www.skillsdirectory.com/skills/reliant-labs-refactor)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: refactor
description: Code refactoring methodology — systematic code transformation patterns, tool selection strategies, and behavior-preserving techniques
---

# Refactoring Methodology

## Refactoring Philosophy

### Behavior Preservation is Paramount

Every refactoring operation must preserve the external behavior of the code. Before making any change, understand what the code does and verify that your transformation maintains that behavior. Run tests before and after refactoring to confirm correctness. If tests don't exist for the code you're refactoring, consider whether tests should be added first.

### Incremental Over Wholesale

Large refactoring efforts should be broken into small, safe nodes. Each step should leave the codebase in a working state. This approach:
- Makes changes easier to review and understand
- Reduces risk of introducing bugs
- Allows for course correction if problems arise
- Creates clear git history showing the transformation

### Understand Before Transforming

Before refactoring any code, develop a deep understanding of:
- What the code does and why
- How other code depends on it
- What patterns and conventions exist in the codebase
- What the original author's intent was
- Whether there are non-obvious reasons for the current structure

## Phase 1: Assessment and Planning

**Code Smell Detection**: Systematically identify code smells that indicate refactoring opportunities:
- Duplicated code across files or functions
- Long methods or functions that do too much
- Large classes with too many responsibilities
- Feature envy where code uses another class's data excessively
- Data clumps where the same group of parameters appears repeatedly
- Primitive obsession using primitives instead of small objects
- Long parameter lists that should be grouped
- Divergent change where one class is modified for different reasons
- Shotgun surgery where one change requires modifying many classes
- Inappropriate intimacy where classes know too much about each other

**Impact Analysis**: Before refactoring, understand the blast radius:
- Use grep to find all usages of the code being refactored
- Identify all files that import or depend on the changed code
- Map the call hierarchy to understand upstream and downstream impacts
- Check for reflection, dynamic dispatch, or other indirect usage patterns
- Identify tests that exercise the code and ensure they pass before changes

**Refactoring Strategy**: Choose the appropriate refactoring pattern:
- Extract Method: Pull code into a new function
- Extract Class: Create new class from existing class's functionality
- Move Method/Function: Relocate to more appropriate location
- Rename: Improve naming for clarity
- Inline: Remove unnecessary indirection
- Replace Conditional with Polymorphism
- Introduce Parameter Object: Group related parameters
- Replace Magic Numbers with Constants
- Decompose Conditional: Simplify complex conditionals

## Phase 2: Pre-Refactoring Verification

**Test Baseline**: Before making any changes:
- Run the existing test suite to establish a passing baseline
- Note which tests cover the code being refactored
- If coverage is insufficient, consider adding characterization tests
- Document the current behavior for comparison after refactoring

**Dependency Mapping**: Create a clear picture of dependencies:
- List all files that will need updates
- Identify any generated code or configuration that references the code
- Check for string-based references (reflection, configuration files, comments)
- Document external API contracts that must be preserved

## Phase 3: Execution with Specialized Tools

**Tool Selection Strategy**:

Use `find_replace` when:
- Renaming identifiers across multiple files
- Updating import statements project-wide
- Changing consistent patterns throughout the codebase
- Replacing deprecated API calls with new ones
- Updating configuration values or constants

Use `move_code` when:
- Relocating functions between files
- Reorganizing code within a file
- Extracting code into new modules
- Reordering methods for logical grouping
- Moving related code closer together

Use `edit` when:
- Making precise, context-dependent changes
- Modifying specific code blocks
- Adding new code alongside existing code
- Making changes that require surrounding context

**Execution Best Practices**:

For each transformation:
1. Read the target file(s) with `view` to understand current state
2. Plan the specific transformation needed
3. Execute using the most appropriate tool
4. Verify the change with `view`
5. Run tests to confirm behavior preservation

## Phase 4: Post-Refactoring Verification

**Functional Verification**:
- Run the full test suite to ensure all tests pass
- Manually verify key functionality if tests are insufficient
- Check for any new compiler warnings or errors
- Verify that the application builds successfully

**Quality Verification**:
- Confirm the refactoring achieved its goals
- Verify naming is clear and consistent
- Ensure new structure follows existing patterns
- Check that documentation is updated if needed

# Common Refactoring Patterns

## Rename Refactoring

When renaming identifiers (functions, variables, types, files):

1. **Assess Scope**: Use grep to find all occurrences
2. **Check for Conflicts**: Ensure new name doesn't conflict with existing names
3. **Execute Rename**: Use find_replace with appropriate scope
4. **Verify Completeness**: Grep for both old and new names to confirm
5. **Update Documentation**: Comments, docs, and string references

Example workflow:
```
# Find all usages
grep "oldFunctionName" --type go

# Review files that will be affected
view each affected file

# Execute rename
find_replace oldFunctionName newFunctionName --file_glob "**/*.go"

# Verify no old references remain
grep "oldFunctionName" --type go

# Run tests
bash "go test ./..."
```

## Extract Function/Method

When code within a function should be its own function:

1. **Identify Boundaries**: Find the exact lines to extract
2. **Determine Parameters**: What data does the extracted code need?
3. **Determine Return Values**: What does the calling code need back?
4. **Check for Side Effects**: Does the code modify external state?
5. **Execute Extraction**: Use edit to create new function and update caller
6. **Verify Behavior**: Run tests to confirm correctness

## Move Code Between Files

When code belongs in a different file:

1. **Identify the Code Block**: Determine exact line range to move
2. **Prepare Target File**: Ensure target has necessary imports
3. **Execute Move**: Use move_code tool with source and target
4. **Update Imports**: Update imports in all dependent files
5. **Clean Up**: Remove unused imports from source
6. **Verify**: Run tests

## Reorganize File Structure

When reordering code within a file for better organization:

1. **Map Current Structure**: Understand what's where
2. **Plan New Structure**: Define the target organization
3. **Execute Moves**: Use move_code for each reordering
4. **Verify Compilation**: Ensure no forward reference issues
5. **Review Result**: Confirm improved organization

# Tool Mastery

## find_replace Excellence

The find_replace tool is powerful for consistent changes across files:

**Literal Matching** (default):
- Use for exact text replacement
- Safe for most identifier renames
- Automatically escapes special characters

**Regex Matching** (use_regex: true):
- Use for pattern-based replacements
- Capture groups ($1, $2) for preserving parts of matches
- Be careful with greedy patterns

**File Scoping** (file_glob):
- Always specify file_glob to limit scope
- Use specific patterns like "**/*.go" for type safety
- Prevents accidental changes in unexpected files

**Pre-Flight Checks**:
- Always grep first to see what will be changed
- Review the list of files that will be modified
- Consider edge cases where pattern might match unintended text

## move_code Excellence

The move_code tool handles code relocation with precision:

**Same-File Moves**:
- Use for reordering functions within a file
- Tool handles line number adjustments automatically
- Useful for grouping related code together

**Cross-File Moves**:
- Source code is removed (move) or kept (copy)
- Target file must exist and be readable
- Imports may need manual adjustment after move

**Line Number Precision**:
- Always view the file first to get accurate line numbers
- Line numbers are 1-indexed and inclusive
- target_line=0 inserts at the very beginning

**Operation Types**:
- "move": Removes from source, adds to target
- "copy": Keeps in source, adds to target

## edit for Context-Sensitive Changes

For changes that require understanding context:

**edit Tool**:
- Best for context-dependent changes
- Requires exact old_string match including whitespace
- Use when change depends on surrounding code
- Supports batched multi-file edits via edits array

# Quality Standards

## Before Completing Any Refactoring

Verify the following checklist:

**Correctness**:
- [ ] All tests pass after refactoring
- [ ] No new compiler/linter errors or warnings
- [ ] Application builds successfully
- [ ] No functional regressions (behavior preserved)

**Completeness**:
- [ ] All references to old code are updated
- [ ] No orphaned imports or unused code introduced
- [ ] Documentation updated if applicable
- [ ] Comments updated to reflect new structure

**Quality**:
- [ ] New code follows existing project patterns
- [ ] Naming is clear, consistent, and meaningful
- [ ] Code organization is logical and intuitive
- [ ] No new code smells introduced

**Safety**:
- [ ] Changes were made incrementally
- [ ] Each step was verified before proceeding
- [ ] Rollback is possible if issues are discovered

# Workspace Awareness

You are working in a git worktree that may be shared with other agents working on related tasks. Before making changes:

1. Run `git status` to understand the current state of the workspace
2. Run `git diff` to see what changes already exist that you didn't make
3. Preserve changes you didn't make — do not revert or overwrite other agents' work unless explicitly told to
4. If you see unexpected changes, they likely belong to another agent — work around them
5. Commit your changes frequently to prevent them from being lost if another process runs `git stash`

# Collaboration Guidelines

## Working with Other Agents

**From Research Agent**: Expect detailed analysis of codebase patterns, architectural decisions, and areas needing refactoring. Use this information to inform your refactoring strategy.

**To Implementation Agent**: After refactoring, provide clear documentation of the new structure, updated patterns, and any changes to conventions that implementation work should follow.

**With Debugging Agent**: If refactoring reveals bugs or issues, document them clearly for debugging. If debugging reveals code that needs refactoring, accept the handoff with context about what's problematic.

## Documentation of Changes

For significant refactoring work, document:
- What was refactored and why
- The pattern or approach used
- Any trade-offs or decisions made
- Impact on other parts of the codebase
- Verification steps performed

Your refactoring work should leave the codebase cleaner, more maintainable, and easier to understand than you found it, while preserving all existing functionality.

Files in this skill

  • SKILL.md11.2 KB
  • migration-guidance/SKILL.md2.8 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.