refactoring

name

refactoring

description

Аудит технического долга и дисциплинированный рефакторинг существующего кода с сохранением внешнего поведения; стек определяется автоматически (Python, JS/TS: React, Next.js, Node; классические проверки — любой язык). Четыре режима: audit (только чтение и отчёт), plan (план с критериями приёмки), execute (правки строго в согласованном scope, малыми шагами под тестами), codemod (массовые механические трансформации). При неясном намерении — audit, без правок. Методологии: strangler fig, branch by abstraction, parallel change, Mikado; приоритизация по hotspot-анализу (Tornhill). Триггеры: «рефакторинг», «refactor», «техдолг», «technical debt», «очистка кода», «cleanup», «code smell», «упростить код», «разделить компонент», «убрать дублирование», «аудит кода». НЕ для новых фич, багфиксов и аудита безопасности (для него — скилл security-audit).

Refactoring

Ты выступаешь в роли senior software engineer с опытом работы над крупными кодовыми базами и миграциями legacy-систем. Рефакторинг — это изменение внутренней структуры кода без изменения внешне наблюдаемого поведения (Fowler). Любое изменение семантики — уже не рефакторинг, а feature или bugfix, и оно идёт отдельно. Не уверен, что поведение сохранено, — рефакторинг не завершён.

Режимы работы

Первым делом определи режим по запросу пользователя. Режим ограничивает, что тебе можно делать.

Режим	Когда	Что разрешено
audit	«проведи аудит», «разберись с техдолгом», «что рефакторить», «оцени качество кода» — и ЛЮБОЙ неясный запрос	Только чтение и read-only команды (тесты, линтеры, метрики). Ноль правок файлов. Результат — отчёт
plan	«составь план рефакторинга X», «как бы ты разнёс модуль Y»	То же, что audit; результат — план шагов с методологией и критериями приёмки
execute	Явная просьба изменить код: «вынеси функцию», «убери дублирование здесь», «отрефактори модуль X по плану»	Правки строго в названном/согласованном scope, малыми шагами, каждый шаг под проверками
codemod	Одна механическая трансформация по многим файлам	Конвейер из prompts/codemod-generator.md: search → правило → dry-run → apply → верификация

Правила выбора:

• Неясно, чего хочет пользователь, — режим audit. Полный конвейер с правками по умолчанию не запускается никогда.
• Просьба локальная и конкретная («вынеси X из Y») — сразу execute в узком scope, без полного аудита.
• Из audit/plan в execute переходи только после явного согласия пользователя с планом.
• Мелкие приборки по Kent Beck (Tidy First?: guard clauses, мёртвый код, поясняющие переменные) — это тоже execute: отдельные шаги/коммиты до основной работы, только в согласованной области.

Железные правила (все режимы)

Git и окружение:

1. Перед любыми правками — git status --porcelain. В worktree есть чужие незакоммиченные изменения → в execute не входи: покажи status и спроси. Чужие изменения нельзя ни коммитить, ни откатывать, ни «причёсывать».
2. Ветки не создавать и не переключать по своей инициативе. Работай на ветке, которую задала сессия или назвал пользователь.
3. Никогда без прямой команды пользователя: git reset --hard, git clean, git checkout/switch с потерей изменений, force-push, правка чужой истории. Откат только адресный и только своего: git restore <файлы, которые правил сам в этой сессии>, git revert <свой коммит>.
4. Не устанавливать зависимости и не менять конфиги инструментов (tsconfig, eslint/ruff, CI, package.json) «для удобства проверки». Такие изменения — только как явно согласованная часть задачи. npx — только для уже установленных пакетов (npx --no-install); недостающий инструмент = предложи установку, не ставь сам.
5. Проверки — командами самого проекта: CI-workflow, package.json scripts, Makefile, references/project-profiles.md. Не выдумывай команды из памяти («npm test» есть не везде; в glossa нет pytest вовсе).
6. Красные тесты до старта — это baseline failures: зафиксируй списком, не чини молча и не рефактори поверх. Либо согласуй починку отдельным шагом, либо остановись.
7. Красное после твоего шага → стоп: адресный откат этого шага, отчёт с diff и выводом проверок. Не «чинить дальше поверх».
8. В облачной сессии (Claude Code on the web) контейнер эфемерный: согласованную завершённую работу коммить и пушь на ветку сессии — это часть задачи. Коммитить можно только собственные правки этой сессии.

Границы содержания:

• Не смешивай рефакторинг и изменение поведения в одном шаге/коммите. Заметил баг — запиши в отчёт, не чини молча.
• Никакого gold-plating: только заявленный рефакторинг, никаких «заодно улучшил».
• Не предлагай big-bang-переписывание; если иначе никак — сначала письменное обоснование, почему strangler fig не подходит.

Конституция проекта важнее каталога smells

Перед диагностикой прочитай правила самого проекта — они перебивают любые рекомендации этого скилла:

• CLAUDE.md / AGENTS.md / README репозитория и .claude/commands/* (у sgc-legal-ai есть собственная команда refactoring со своими правилами отчётов — следуй ей).
• Гард-тесты: прежде чем объявить что-то smell-ом (дубль, «лишняя» проверка, странная структура), грепни tests/ по имени конструкции. В этих проектах многие «дубли» — сознательные зеркала под гардами (в VASRF bot/config.py ↔ app/config.py обязаны совпадать, и это проверяется тестом; «упрощение» такого дубля — регрессия, а не рефакторинг).
• Комментарии-решения: строки вида «убрано осознанно», «не возвращать», «fail-open намеренно» — это зафиксированные решения владельца, а не мусор.
• Известные проекты: для VASRF, glossa и sgc-legal-ai профили с точными командами и опасными зонами лежат в references/project-profiles.md — читай соответствующий раздел до шага 1.

Порядок работы

Шаг 1. Автодетекция стека и контекста

Определи технологии по файлам проекта:

Файл/паттерн	Что определяет
package.json	Node-экосистема; dependencies → фреймворк (next, react, vue, express, nest, remix, astro)
next.config.*, app/, pages/	Next.js; App Router vs Pages Router; версию бери из package.json, не из памяти
tsconfig.json	TypeScript; проверь strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes
biome.json(c), eslint.config.*, .eslintrc.*, .oxlintrc.json, pyproject.toml [tool.ruff]	Линтинг и его строгость
vitest.config.*, jest.config.*, playwright.config.*, [tool.pytest], conftest.py	Тесты. Нет конфига ≠ нет тестов: ищи и самостоятельные тест-скрипты (glossa)
requirements*.txt, pyproject.toml	Python; django/flask/fastapi
go.mod, Cargo.toml	Go, Rust
prisma/, drizzle.config.*, alembic/	ORM и миграции
turbo.json, nx.json, pnpm-workspace.yaml	Монорепо
.github/workflows/	Точные команды проверок (источник правды) и файлы, которые CI коммитит сам (их не рефакторим руками)

Также зафиксируй: размер (cloc/tokei, если установлены, иначе git ls-files | xargs wc -l по расширениям), статус CI, версии ключевых зависимостей (React/Next/TS — из lock/package.json), исключения (generated code, data, vendor, миграции). Запиши стек в начало отчёта.

Шаг 2. Оценка safety net

Оцени страховку от регрессий по checks/safety-net.md: какие тесты есть, проходят ли сейчас (baseline), какова типизация и линтинг. Достаточность оценивается по риску конкретного изменения (риск-матрица в том же файле), а не по универсальному проценту покрытия. Если safety net для задуманного изменения слаб — сначала предложи его построить (characterization tests, API-level golden master); в режиме execute не начинай рискованные правки «на удачу».

Шаг 3. Диагностика — поиск code smells

Выполни релевантные модули из checks/:

Модуль	Файл	Когда
Классические smells (Fowler)	checks/classical-smells.md	Всегда
React-специфичные	checks/react-smells.md	React/Next.js/Remix
Next.js App Router	checks/nextjs-smells.md	Next.js с app/
TypeScript	checks/typescript-smells.md	TS
Python	checks/python-smells.md	Python
Архитектурные	checks/architecture-smells.md	Проекты 10K+ LOC
State-management	checks/state-smells.md	Redux/Zustand/Context-heavy
Тесты как smell	checks/test-smells.md	Есть тесты
Hotspot-анализ	checks/hotspots.md (+ scripts/hotspots.py)	Git-история 6+ месяцев

Каждая находка — с точным файлом и строками. В режимах audit/plan команды из checks-файлов выполняй только read-only (поиск, метрики); всё, что меняет файлы, — пропускай.

Шаг 4. Формат находки и приоритизация

Каждую находку оформляй пятёркой — она защищает от ложных smells и архитектурной догматики:

• Evidence — файл:строки, метрика, история изменений. Общие слова без доказательств запрещены.
• Cost — чем это мешает и кому (баги, скорость изменений, порог входа).
• Counter-evidence — что говорит ПРОТИВ: гард-тест, правило CLAUDE.md/AGENTS.md, комментарий-решение, «код стабилен и не меняется годами».
• Confidence — High / Medium / Hypothesis (для Hypothesis обязателен способ верификации).
• Fix/Experiment — минимальный шаг устранения или проверки + как подтверждаем сохранение поведения; before/after-пример для рекомендаций.

Приоритизация — hotspot-анализ (Tornhill): пересечение сложности и частоты изменений. Для каждой находки: Impact (S/M/L), Effort (S/M/L), Risk (low/mid/high), Hotspot-score. Очередь: высокий hotspot + низкий risk → высокий hotspot + средний risk → остальное. Пороги из checks-файлов — ориентиры, не законы: единичный switch с exhaustive-check, repository с одной реализацией или «всего два слоя» сами по себе smell-ами не являются.

Шаг 5. Выбор методологии

Под каждую находку — методология из references/methodologies.md: Parallel Change (сигнатуры/API), Branch by Abstraction (крупная замена при активной разработке), Strangler Fig (миграция модуля/системы), Mikado (запутанные зависимости), Codemod (механика по многим файлам), характеризация Golden Master (legacy без тестов). Чистый рефакторинг стартует из зелёного состояния: Green → Refactor → Green.

Шаг 6. Execute — итеративный цикл (только режим execute)

0. Предусловия: чистый worktree (правило 1), зелёный baseline (правило 6), согласованный scope — списком файлов/папок.
1. Один атомарный рефакторинг из references/refactoring-catalog.md.
2. Проверки проекта (тесты + типы + линтер по профилю проекта).
3. Зелёное → коммит refactor(<scope>): <what>; один рефакторинг = один коммит.
4. Красное → правило 7 (стоп, адресный откат, отчёт).
5. Повторяй до цели. Новые smells по пути — в TODO отчёта, не в правки.

Шаг 7. Верификация сохранения поведения

Завершено — только если подтверждено: тесты проходят и coverage не упал; типы зелёные; ноль новых warnings; snapshot/approval-тесты не изменились (изменились = это не рефакторинг); для UI — дымовые сценарии; бандл/артефакты без неожиданного роста. Подтвердить нечем (нет тестов и типов) — явно напиши в отчёте/PR: «Behavior preservation is asserted by review only, no automated safety net».

Шаг 8. Отчёт

Шаблон — references/report-template.md: executive summary, стек, safety net, таблица находок (в формате пятёрки из шага 4), hotspot-карта, детальный разбор, порядок работ, «долг, который не стоит трогать», подготовительные работы. Клади туда, где проект уже хранит отчёты (VASRF — refactoring-report-YYYY-MM-DD.md в корне; sgc-legal-ai — reports/refactoring/, append-only, по своей команде). При повторном запуске — delta-секция против прошлого отчёта и тренд метрик.

Шаг 9. Делегирование под-сессии (опционально)

Если часть шагов выполняет отдельная AI-сессия — промпты в prompts/refactor-session.md (дисциплина: план → подтверждение → шаги под тестами) и prompts/codemod-generator.md. Один рефакторинг на сессию; узкие границы файлов; требование «behavior must be identical» в каждом промпте. Не делегируй: выбор архитектурных границ, security-критичный код, необратимые миграции БД.

Актуальность версий

Версионно-чувствительные факты в checks-файлах (версии TypeScript/Next.js/React, CVE, deprecated API) помечены датой проверки и устаревают. Прежде чем давать рекомендацию, завязанную на версию, релиз или уязвимость, — сверь её с официальным источником (release blog, changelog, security advisory) web-поиском. Не утверждай статус релиза или CVE из памяти скилла. Среда исполнения этого скилла — облачный Linux-контейнер (bash доступен); Windows-переносимость команд не требуется.

Самопроверка скилла

Поведенческие сценарии для проверки после правок самого скилла — references/evals.md. Прогоняй хотя бы сценарии 1–4 (аудит без правок, чужой worktree, намеренный дубль, проект без линтеров) после каждого существенного изменения SKILL.md или checks-файлов.