К основному содержанию
команда CX Codex

refactor-guided — команда для Claude Code: рефакторинг

Команда refactor-guided проводит структурный рефакторинг по шагам и проверяет тесты после каждого изменения. Подходит для безопасной перестройки кода без добавления функций.

MIT ★ 1 424 обновлён 2026-10-06

Установить в Claude Code · Вручную: положить файлы Все способы и платформы ↓
.claude/commands/refactor-guided.md
Открыть на GitHub

Что делает refactor-guided

Команда сначала определяет область изменений: целевые файлы, зависимости, зависимые модули и возможный радиус затрагивания. Затем проверяет существующие тесты, при необходимости добавляет покрытие текущего поведения и фиксирует исходный результат.

Рефакторинг идёт небольшими шагами. После каждого изменения команда запускает тесты, при успехе создаёт отдельный коммит с префиксом refactor:, а при сбое откатывает попытку и разбирает причину. Она умеет извлекать функции, переименовывать элементы, убирать дублирование, упрощать условия и разделять крупные файлы.

При незакоммиченных изменениях команда остановится и попросит решить, что с ними делать, поэтому чистое рабочее дерево нужно подготовить заранее. Для работы используются git, менеджеры пакетов, тестовые команды и инструменты чтения и редактирования файлов.

Какие задачи решает

  • разбить крупный файл или функцию на части
  • переименовать элементы без изменения внешнего поведения
  • убрать дублирование в коде
  • проверить рефакторинг тестами после каждого шага
  • зафиксировать структурные изменения отдельными коммитами

Примеры запросов агенту

  • Запусти /refactor-guided для анализа последних изменённых файлов и предложи безопасные шаги рефакторинга.
  • Запусти /refactor-guided и вынеси повторяющуюся логику из src/orders.ts в отдельную функцию.
  • Запусти /refactor-guided для каталога src/api и проверяй тесты после каждого изменения.

Как установить refactor-guided

Вручную: положить файлы

.claude/commands/refactor-guided.md

Вызов — /refactor-guided. Для всех проектов — ~/.claude/commands/

Вопросы о refactor-guided

Как установить refactor-guided в Claude Code?

Поместите файл команды в .claude/commands/refactor-guided.md. После этого вызовите её в Claude Code через /refactor-guided.

Что делает refactor-guided?

Команда анализирует область рефакторинга, проверяет тестовое покрытие и применяет структурные изменения по одному. После каждого шага она запускает тесты и создаёт отдельный коммит или откатывает неудачную попытку.

Что произойдёт, если в рабочем дереве есть незакоммиченные изменения?

Команда остановится и попросит пользователя решить, как с ними поступить. Она не будет самостоятельно прятать или коммитить эти изменения.

Исходный текст

refactor-guided.md · MIT
---
allowed-tools: Bash(git:*), Bash(npm:*), Bash(npx:*), Bash(yarn:*), Bash(pnpm:*), Bash(bun:*), Bash(pytest:*), Bash(python:*), Bash(go:*), Bash(cargo:*), Read, Write, Edit, Glob, Grep
description: Systematic, safety-first refactoring with verification at each step. Never refactors and adds features simultaneously.
argument-hint: "[target file, directory, or refactoring description]"
---

# Guided Refactoring

Perform safe, incremental refactoring with test verification at every step.

## Context

- Recent changes: !`git diff --name-only HEAD~3 2>/dev/null | head -10`
- Current branch: !`git branch --show-current`
- Working tree status: !`git status --short`
- Project root files (infer the test framework from these): !`ls -a`
- Existing tests: !`git ls-files 2>/dev/null | grep -i -e test -e spec | head -10`

## Safety Rules (NON-NEGOTIABLE)

1. **NEVER refactor AND add features simultaneously.** Each change is purely structural.
2. **NEVER proceed without passing tests.** If tests fail after a refactoring, revert immediately.
3. **ONE refactoring at a time.** Each commit is a single, atomic refactoring step.
4. **Preserve external behavior.** Inputs and outputs must remain identical.
5. **Ensure clean working tree before starting.** If there are uncommitted changes, stop and ask the user — do not stash or commit their work yourself.

## Workflow

### Phase 1: Analyze Scope

1. Identify the target file(s) or directory from `$ARGUMENTS`
2. Map all dependents — files that import/use the target
3. Map all dependencies — files that the target imports/uses
4. Assess blast radius: how many files could be affected?
5. Report scope summary before proceeding:
   ```
   ## Refactoring Scope
   - Target: [file/directory]
   - Files affected: [count]
   - Dependencies: [list]
   - Dependents: [list]
   - Risk level: [low/medium/high]
   ```

### Phase 2: Ensure Test Coverage

1. Check if tests exist for the current behavior of the target
2. Run existing tests to confirm they pass (this is your safety net)
3. If test coverage is insufficient:
   - Write tests that capture the current behavior BEFORE refactoring
   - Run them to confirm they pass
   - Commit these tests separately: `test: add coverage for [target] before refactoring`
4. Record baseline test results (pass count, time)

### Phase 3: Refactor Incrementally

For each refactoring step:

1. **Describe** the specific refactoring about to be applied (e.g., "Extract method X from class Y", "Rename variable A to B", "Move function to separate module")
2. **Apply** the single refactoring change
3. **Run tests** immediately after applying
4. **If tests PASS:**
   - Commit with message: `refactor: [specific change description]`
   - Move to next refactoring step
5. **If tests FAIL:**
   - Revert the change: `git checkout -- .`, and delete any new files this step created (they are untracked, so checkout leaves them behind)
   - Analyze why it failed
   - Try a different approach or break it into smaller steps
   - Document what went wrong

Common refactoring types (apply as appropriate):

- Extract function/method
- Rename for clarity
- Remove duplication (DRY)
- Simplify conditionals
- Split large files/functions
- Improve type signatures
- Replace magic values with constants
- Consolidate imports

### Phase 4: Summary Report

After all refactoring steps are complete, provide:

```
## Refactoring Summary

### Before
- Files: [count and names]
- Lines of code: [approximate]
- Complexity: [observations]

### After
- Files: [count and names]
- Lines of code: [approximate]
- Complexity: [observations]

### Changes Applied
1. [refactoring 1] - [commit hash]
2. [refactoring 2] - [commit hash]
...

### Reverted Attempts
1. [what was tried] - [why it failed]

### Test Results
- All tests passing: [yes/no]
- Tests added: [count]
- Total test runs: [count]
```

## Target

$ARGUMENTS

If no target specified, analyze the most recently modified files and suggest refactoring opportunities.

© CloudAI-X · MIT · CloudAI-X/claude-workflow-v2

Похожие слэш-команды

Все слэш-команды по теме «Код-ревью и рефакторинг» →
refactor SethGammon Скилл refactor для Claude Code выполняет рефакторинг нескольких файлов с автооткатом через Git, проверкой типов и тестами до и после правок. CX Codex +1 ★ 937звёзд репо review-and-refactor официальный github Скилл review-and-refactor проверяет код проекта по локальным инструкциям и рефакторит участки, которым нужна правка. Подходит перед ревью или очисткой существующего кода. CX Codex +1 11 056установок code-refactor-review jnsahaj Скилл code-refactor-review для Claude Code разбирает diff и PR на повторное использование, связность и соответствие стилю проекта. Проверяет рефакторинг. CX Codex +1 181установок refactor-method-complexity-reduce официальный github Скилл refactor-method-complexity-reduce рефакторит выбранный метод, снижая когнитивную сложность через вынос логики в хелперы. Подходит для длинных ветвлений и вложенных условий. CX Codex +1 9 992установок w-refactor blockmatic-icebox Скилл w-refactor для Claude Code помогает менять структуру кода, сохраняя его поведение. Перед правками он предлагает зафиксировать исходное поведение тестами, проверками типов или ручным сценарием. CX Codex +1 647установок refactor-legacy-code aj-geddes Скилл refactor-legacy-code помогает пошагово обновлять старый код без поломки логики. Пригодится при разборе техдолга и устаревших API. CX Codex +1 611установок

Из того же набора46

Весь набор →
verify-changes Команда verify-changes запускает параллельную проверку свежих правок через субагентов и состязательный фильтр ложных срабатываний. CX Codex +1 ★ 1 424звёзд репо save-session-learnings Команда save-session-learnings переносит важные выводы из сессии в CLAUDE.md и AGENTS.md. Запускайте её после отладки или крупной задачи, чтобы сохранить контекст для следующих сессий. CX Codex +1 ★ 1 424звёзд репо analyzing-projects Скилл analyzing-projects разбирает незнакомый репозиторий по шагам: стек, структура, паттерны, команды разработки — пригодится при входе в новый проект. CX Codex +1 ★ 1 424звёзд репо plan Создаёт и ведёт файл PLAN.md в корне проекта для фиксации этапов разработки, зависимостей между задачами и лога прогресса. CX Codex +1 ★ 1 424звёзд репо convex-backend Скилл convex-backend загружает guidelines для работы с Convex: функции, схемы, валидаторы, queries, mutations, actions, подписки и хранилище файлов. Помогает писать типобезопасный бэкенд на TypeScript. CX Codex +1 ★ 1 424звёзд репо dependency-upgrade Команда dependency-upgrade для Claude Code поочерёдно обновляет зависимости, запускает тесты после каждого пакета и откатывает изменения при ошибках. CX Codex +1 ★ 1 424звёзд репо designing-apis Скилл designing-apis в Claude Code проектирует REST и GraphQL API: структурирует эндпоинты, описывает форматы запросов и ответов, настраивает обработку ошибок и версионирование. CX Codex +1 ★ 1 424звёзд репо parallel-analyze Команда parallel-analyze запускает четыре субагента разом: архитектура, безопасность, производительность и тесты. Сводит их находки в один отчёт с приоритетами. CX Codex +1 ★ 1 424звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой