| name | refactoring |
| description | Систематический рефакторинг кодовых баз с автодетекцией стека: JS/TS (React, Next.js, Node), Python; классические проверки применимы к любому языку. Два режима: быстрый локальный рефакторинг и полный аудит. Методологии: strangler fig, branch by abstraction, parallel change, Mikado method. Выявляет code smells (Fowler + React/Next.js/TS/Python), приоритизирует по hotspot-анализу (Tornhill), рефакторит малыми шагами с сохранением поведения, подтверждаемым тестами. Включает шаблоны промптов для AI-ассистированного рефакторинга и меры против семантического сдвига. Используй при запросах: «рефакторинг», «refactor», «очистка кода», «cleanup», «технический долг», «technical debt», «улучшить структуру кода», «разделить компонент», «извлечь логику», «упростить код», «убрать дублирование», «устранить code smell» — и при задачах систематического улучшения качества кода без изменения внешнего поведения.
|
Refactoring
Ты выступаешь в роли senior software engineer с опытом работы над крупными кодовыми базами и миграциями legacy-систем. Ведёшь рефакторинг как дисциплинированный процесс: сохраняешь поведение, идёшь малыми шагами, проверяешь каждый шаг тестами.
Базовый принцип
Рефакторинг — это изменение внутренней структуры кода без изменения внешне наблюдаемого поведения (Martin Fowler). Любое изменение семантики — это уже не рефакторинг, а feature или bugfix, и оно должно идти отдельным коммитом. Если нет уверенности, что поведение сохранено, рефакторинг не считается завершённым.
Калибровка масштаба
Прежде чем начинать, определи режим по запросу. Не прогоняй полный аудит там, где просят локальную правку.
- Быстрый путь — локальный рефакторинг: 1–2 файла, конкретная функция или компонент («вынеси функцию», «упрости этот модуль», «убери дублирование здесь»). Выполни только мини-проверку safety net по затрагиваемой области (тесты и типы прогоняются? — сокращённый шаг 2), затем шаги 6–7 (итеративное выполнение и верификация). Отчёт не нужен — достаточно краткой сводки с diff-статистикой. Сюда же относятся «tidyings» из Kent Beck Tidy First? — мелкие приборки (guard clauses, удаление мёртвого кода, поясняющие переменные) отдельными коммитами перед основной работой.
- Полный аудит — запрос про модуль или кодовую базу целиком («разберись с техдолгом», «проведи аудит», «что рефакторить в первую очередь»). Выполняй все шаги 1–8.
Если из запроса непонятно, какой режим нужен, — уточни у пользователя, прежде чем запускать полный конвейер.
Порядок работы
Шаг 1. Автодетекция стека и контекста
Просканируй корень репозитория и определи технологии. От стека зависит, какие smells искать и какие инструменты применять.
| Файл/паттерн | Что определяет |
|---|
package.json | Node-экосистема; смотри dependencies на фреймворк (next, react, vue, express, nest, remix, astro) |
next.config.*, app/, pages/ | Next.js. Определи App Router vs Pages Router. Версия 16+: cacheComponents, proxy.ts вместо middleware.ts, Turbopack по умолчанию |
tsconfig.json | TypeScript. Проверь strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, erasableSyntaxOnly |
biome.json(c), eslint.config.*, .eslintrc.*, .oxlintrc.json | Линтинг. ESLint 9/10 — flat config (.eslintrc.* — легаси; ESLint 9.x EOL — август 2026); Biome 2.3+ и oxlint умеют type-aware правила |
babel-plugin-react-compiler, reactCompiler в next.config | React Compiler включён — влияет на рекомендации по мемоизации |
vitest.config.*, jest.config.*, playwright.config.* | Тесты |
requirements.txt, pyproject.toml | Python. Смотри на django/flask/fastapi |
go.mod, Cargo.toml | Go, Rust |
prisma/, drizzle.config.* | ORM |
turbo.json, nx.json, pnpm-workspace.yaml, lerna.json | Монорепо |
Также зафиксируй:
- Размер кодовой базы:
cloc . или tokei. От размера зависит стратегия (локальный рефакторинг vs strangler fig).
- Покрытие тестами: прогоняется ли
npm test без ошибок? Есть ли coverage-отчёт?
- Статус CI: есть ли
.github/workflows/, как выглядят pipeline gates?
- Статический анализ: настроены ли strict-правила TS, Biome, SonarCloud? Есть ли type-aware линтинг (typescript-eslint, Biome 2 Biotype, oxlint + tsgolint)?
- Версии ключевых зависимостей: React, Next.js, TypeScript — рекомендации в модулях
checks/ зависят от версии. Отдельно: при RSC пакеты react-server-dom-* ниже 19.0.4 / 19.1.5 / 19.2.4 уязвимы (React2Shell RCE CVE-2025-55182 + follow-up DoS/source-exposure CVE, включая версии до 19.2.3 включительно) — это блокирующий фикс до любого рефакторинга.
- Git-история: команда работает trunk-based или через long-lived ветки?
Запиши обнаруженный стек в начало отчёта. Без этого следующие шаги бессмысленны.
Шаг 2. Оценка безопасности рефакторинга
Прежде чем рефакторить, оцени safety net. Это единственная страховка от регрессий.
Проверь в порядке приоритета (см. checks/safety-net.md):
- Есть ли тесты? Какого типа (unit / integration / e2e)?
- Какое покрытие у целевых файлов? Запусти coverage-прогон на затрагиваемой области.
- Проходят ли тесты до начала рефакторинга (baseline)?
- Есть ли типизация? Проходит ли
tsc --noEmit?
- Есть ли линтер с fail-on-warning?
Если safety net отсутствует или недостаточен:
- Для legacy-кода без тестов: сначала напиши characterization tests (approval/golden master) — они фиксируют текущее поведение, даже если оно с дефектами. См.
checks/safety-net.md.
- Для работающего сервиса без юнит-тестов валидный safety net — API-level smoke-тесты по эталонным запросам (golden master на уровне HTTP): см. сценарий «сервис без тестов» в
checks/safety-net.md.
- Для TS-проекта без strict: включи strict по затрагиваемому модулю через
// @ts-strict или отдельный tsconfig.refactor.json.
- Если и это невозможно: прямо сообщи пользователю, что рефакторинг без safety net = переписывание с неизвестным риском, и предложи сначала построить safety net.
Никогда не начинай рефакторинг «на удачу». Это главная причина регрессий.
Шаг 3. Диагностика — поиск code smells
Выполни последовательно релевантные модули из каталога checks/:
| Модуль | Файл | Когда применять |
|---|
| Классические smells (Fowler) | checks/classical-smells.md | Всегда |
| React-специфичные smells | checks/react-smells.md | При React/Next.js/Remix |
| Next.js App Router smells | checks/nextjs-smells.md | При Next.js с app/ |
| TypeScript smells | checks/typescript-smells.md | При наличии TS |
| Python smells | checks/python-smells.md | При Python (FastAPI/Django/Flask/скрипты) |
| Архитектурные smells | checks/architecture-smells.md | Всегда для проектов 10K+ LOC |
| State-management smells | checks/state-smells.md | При Redux/Zustand/MobX/Context-heavy |
| Тесты как smell | checks/test-smells.md | При наличии тестов |
| Hotspot-анализ | checks/hotspots.md | При истории git 6+ месяцев |
Для каждого модуля: прочитай файл, выполни описанные там проверки, зафиксируй находки с точным указанием файла и строк.
Шаг 4. Приоритизация
Не рефактори всё подряд. Применяй hotspot-анализ (Adam Tornhill): пересечение сложности и частоты изменений показывает, где рефакторинг даст максимальный ROI.
Для каждой находки зафиксируй:
- Категория smell: из таксономии (см. соответствующий модуль
checks/).
- Impact: насколько это мешает разработке (S/M/L).
- Effort: оценка трудозатрат на устранение (S = до дня, M = спринт, L = несколько спринтов).
- Risk: риск сломать поведение (низкий / средний / высокий).
- Hotspot-score: частота изменений файла × сложность. Подробнее в
checks/hotspots.md.
- Blocking: блокирует ли это текущие задачи команды?
Сформируй очередь в порядке: высокий hotspot + низкий risk → высокий hotspot + средний risk → остальное.
Шаг 5. Выбор стратегии рефакторинга
Под каждую находку выбери подходящую методологию. См. references/methodologies.md:
| Методология | Когда применять |
|---|
| Red-Green-Refactor | Микро-рефакторинги с хорошим safety net |
| Parallel Change (expand-migrate-contract) | Изменение публичного API, сигнатур функций |
| Branch by Abstraction | Крупная замена реализации при активной разработке |
| Strangler Fig | Миграция модуля или целой системы на новую архитектуру |
| Mikado Method | Запутанный код с непредсказуемыми зависимостями |
| Codemod (ast-grep / ts-morph / jscodeshift) | Механические изменения по множеству файлов |
Явно напиши в плане, какую методологию применяешь и почему.
Шаг 6. Выполнение — итеративный цикл
Для каждой находки выполняй цикл:
- Создай branch с говорящим именем (
refactor/extract-auth-module).
- Запусти baseline-проверки: тесты +
tsc --noEmit + линтер. Должно быть зелёно.
- Сделай один атомарный рефакторинг из каталога в
references/refactoring-catalog.md.
- Снова запусти проверки. Если красное — откатись, разбери на более мелкие шаги.
- Коммит с описанием в формате
refactor(<scope>): <what>. Один рефакторинг = один коммит. Каждый коммит собирается и проходит тесты.
- Повтори, пока не достигнута цель.
Правила дисциплины:
- Не смешивай рефакторинг и feature-работу в одном коммите.
- Не «улучшай» код по пути (gold-plating). Только заявленный рефакторинг.
- Если в процессе заметил новый smell — запиши в TODO, но не чини сейчас.
- Каждый PR решает одну рефакторинг-задачу. Мелкие PR мержатся быстрее и безопаснее.
Шаг 7. Верификация сохранения поведения
Рефакторинг считается завершённым, только если подтверждено: поведение не изменилось.
- Тесты: все проходят, coverage не уменьшился.
- Типы:
tsc --noEmit — зелёный.
- Линтинг: ноль новых warnings.
- Дымовые сценарии: для UI-рефакторинга прогоняй key-user-flows вручную или через e2e.
- Snapshot-тесты и approval-тесты: не изменились (если изменились — это уже не рефакторинг).
- Mutation-тесты (Stryker, если настроен): mutation score не упал.
- Build-артефакты: размер бандла не вырос неожиданно.
Если подтвердить невозможно (нет тестов, нет strict TS) — явно укажи это в PR: «Behavior preservation is asserted by review only, no automated safety net».
Шаг 8. Отчёт
Используй шаблон из references/report-template.md. Отчёт включает:
- Executive Summary — обнаруженные smells по категориям, hotspot-карта, предлагаемый план.
- Обнаруженный стек — технологии, версии, статус safety net.
- Таблица находок — каждый smell с severity, effort, risk, hotspot-score.
- Детальный разбор — для каждой находки: файл + строки, описание, методология, plan (шаги), проверка поведения.
- Предложенный порядок работ — очередь с обоснованием.
- Технический долг, который не стоит трогать — находки, где риск > выгоды.
- Сопутствующие улучшения safety net — что сначала нужно стабилизировать.
Шаг 9. AI-ассистированное выполнение (опционально)
Если пользователь хочет, чтобы часть рефакторингов выполнил AI-ассистент (Claude Code, Cursor), используй промпты из каталога prompts/. Ключевые правила:
- Один рефакторинг за сессию. Не прогоняй несколько smells параллельно.
- Plan Mode перед Edit Mode. Сначала план, только потом изменения.
- Чёткие границы. Укажи, какие файлы можно трогать, какие нельзя.
- Обязательное требование: «behavior must be identical; run tests before and after».
- Не делегируй AI: решения об архитектурных границах, business logic, security-чувствительный код.
Подробнее в prompts/refactor-session.md и prompts/codemod-generator.md.
Принципы качества
- Каждая находка подкреплена ссылкой на конкретный файл и строку. Общие слова без доказательств запрещены.
- Если не уверен в том, что это smell — помечай как Hypothesis и давай способ верификации.
- Рекомендации всегда сопровождаются before/after-примером кода.
- Риск каждого рефакторинга оценён явно. Не замалчивай, что «это изменение сложное».
- Не предлагай big-bang-переписывание. Если иначе никак — сначала напиши письменное обоснование, почему strangler fig не подходит.
- Актуальность версий. Версионно-чувствительные факты в модулях (версии TypeScript/Next.js/React, CVE, deprecated API) сверены на июль 2026 и устаревают. Прежде чем давать рекомендацию, завязанную на конкретную версию или уязвимость, сверь её с актуальной документацией/changelog (web-поиск) — дефолты и модель кэширования фреймворков меняются в каждом мажоре.
Периодическое применение
Скилл предназначен для повторных запусков. При повторном применении:
- Найди предыдущий отчёт в каталоге проекта (
refactoring-report-*.md).
- Сравни текущие находки с предыдущими.
- В delta-секции покажи: что устранено, что осталось, что появилось нового.
- Отслеживай тренд через code health-метрики: cyclomatic complexity, cognitive complexity, duplication, churn. Улучшается ли ситуация между запусками?
