раздел 11 · рецепт

Рефакторинг большого кодовозака

Когда у вас 500+ файлов и нужно поменять что-то поперёк всего проекта - переименовать функцию, мигрировать на новый API, выкинуть устаревший паттерн - наивный подход "попроси Claude" не работает. Контекст переполняется, Claude теряет нить, начинает галлюцинировать. Этот рецепт - как делать большой рефакторинг без слёз.

Когда применять

  • Переименование функции/типа, используемого в 50+ файлах
  • Миграция всего проекта с одного паттерна на другой (Redux → Zustand, Class Components → Hooks)
  • Удаление устаревшего API из всего кода
  • Унификация кодстайла (имена endpoints, имена компонентов)

Шаги

Шаг 1. Inventory - что трогаем

Не лезьте сразу в код. Сначала узнайте масштаб.

Промпт:
"Делегируй субагенту Explore: найди все упоминания getCwd в .ts/.tsx файлах
проекта. Верни список файл:строка плюс контекст ±2 строки. Не редактируй ничего."

Получаете отчёт. Если упоминаний < 20 - делаете руками за час, рефакторинг не нужен. Если > 100 - читайте дальше.

Шаг 2. Migration plan

Прежде чем менять код, попросите Claude составить план в plan-mode.

1. Нажмите Shift+Tab → переключитесь в plan mode
2. Промпт: "Спланируй миграцию getCwd -> getCurrentWorkingDirectory.
   Учти: разные сигнатуры в разных файлах, мокаются в тестах,
   используется в .tsx через React Context. Раздели на этапы
   так, чтобы каждый этап можно было закоммитить и протестировать
   независимо."
3. Получите план из 5-8 этапов с зависимостями
4. ExitPlanMode когда согласны с планом

Шаг 3. Делегирование по пакетам

Теперь рефакторим этапами. Для каждого этапа:

Промпт:
"Этап 2 из плана: замени getCwd на getCurrentWorkingDirectory во всех
файлах внутри src/utils/. Не трогай тесты пока. После каждого файла
запускай tsc --noEmit на этом файле. Если падает - откатись и сообщи мне."

После завершения каждого этапа:

git add -A
git commit -m "refactor: rename getCwd in src/utils/"
npm test

Если тесты упали - не идите дальше. Зовите Claude чинить, или откатывайте этап.

Шаг 4. Параллельные worktree (опционально)

Если рефакторинг затронет 5+ независимых директорий, создайте worktree под каждую:

git worktree add ../app-refactor-utils refactor-utils
git worktree add ../app-refactor-components refactor-components
git worktree add ../app-refactor-pages refactor-pages

В каждом worktree - свой Claude в отдельном терминале. Через час сводите всё в main.

Антипаттерны

| Что не делать | Почему | |---|---| | "Поменяй getCwd везде" одним промптом | Контекст переполнится, Claude забудет файлы. | | Рефакторинг без plan-mode | Половина изменений будет неправильной. | | Рефакторинг без тестов | Не узнаете, что сломали, до прода. | | Мерж в main без code review | Большой рефакторинг = много мест для ошибок. | | Удалять старый API сразу | Сделайте deprecation на 1 релиз, потом удалите. |

Точки сохранения

После каждого этапа из плана - обязательно git commit. Тогда git revert <commit> точечно откатит проблемный шаг, не трогая остальные.

Полезные ссылки