Старый код страшно трогать — одно неосторожное движение, и всё едет. Claude Code помогает переписывать безопасно: сеть из тестов, маленькие шаги, проверка на каждом и откат под рукой. Разберём воркфлоу, который не ломает прод.
Легаси (legacy) — это старый код, который работает, но трогать его страшно: автор давно ушёл, тестов нет, а как именно всё устроено — никто уже не помнит. Соблазн отдать такой файл Claude с просьбой «перепиши красиво» велик, но это худший способ. Безопасный рефакторинг с агентом — это не «перепиши всё», а дисциплина из четырёх правил: сначала тесты, потом маленькие шаги, проверка на каждом, откат наготове. Разберём каждое.
Что узнаешь из гайда
Часть 1 · Понятие
Главное
Рефакторинг — это чистка структуры без смены поведения. Снаружи код работает ровно как раньше, меняется только то, как он устроен внутри. Это и есть его безопасность.
Разведём два слова. Рефакторинг — улучшение структуры кода так, чтобы наблюдаемое поведение не изменилось ни на йоту: те же входы дают те же выходы. Переписывание — это когда ты заодно меняешь и логику. Разница принципиальная: после рефакторинга есть объективный критерий «не сломал» — поведение совпадает. После переписывания такого критерия нет, потому что поведение специально поменяли.
Поэтому с незнакомым легаси работаем именно как с рефакторингом: держим поведение зафиксированным и меняем только форму. Если по дороге нужно и поведение поменять — это отдельная задача после рефакторинга, а не вместе с ним. Один шаг — одна цель.
| Подход | Поведение | Как проверить «не сломал» |
|---|---|---|
| Рефакторинг | Не меняется | Тесты до и после зелёные |
| Переписывание | Меняется | Объективного критерия нет |
Часть 2 · Страховка
Главное
Перед любой правкой попроси Claude написать тесты на текущее поведение. Это страховочная сеть: она фиксирует, как код работает сейчас, и поймает момент, когда что-то поедет.
Тест — это маленькая программа, которая проверяет, что код выдаёт ожидаемый результат. «Сеть из тестов» на текущее поведение работает так: ты фиксируешь, что код делает сейчас (даже если делает странно), и любое изменение, которое это поведение ломает, сразу подсветит красный тест. Без сети ты меняешь код вслепую.
> Не меняй логику. Сначала разберись, что делает функция calculateInvoice
> в billing.js, и напиши тесты, фиксирующие её ТЕКУЩЕЕ поведение —
> включая крайние случаи (ноль, отрицательные, пустой ввод).
> Прогони тесты, они должны быть зелёными на старом коде.Ключевая формулировка — «фиксирующие текущее поведение». Не «как должно быть», а «как есть». Цель сети не починить логику, а заметить, если рефакторинг её случайно сдвинет. Подробно про цикл «сначала тест — потом код» — в гайде про тесты и TDD-воркфлоу.
Важно
Тесты на текущее поведение должны быть зелёными до рефакторинга. Если они сразу красные — значит, ты ещё не понял, что код реально делает, и менять его рано. Сеть имеет смысл только когда она ловит регресс, а не путается в исходном поведении.
Часть 3 · Темп
Главное
Большую переделку дроби на серию мелких правок. После каждой — прогон тестов. Зелёные — шаг закреплён, идём дальше. Красные — откат именно этого шага, а не всего.
Главная ошибка — попросить «перепиши весь файл». Claude уверенно выдаст результат, но если в нём ошибка, искать её придётся среди сотен новых строк. Маленький шаг (переименовать переменные, вынести одну функцию, убрать дублирование в одном месте) проверяется мгновенно: тесты либо зелёные, либо ткнут точно в этот шаг.
> Рефакторим billing.js по одному шагу за раз, не больше.
> Шаг 1: вынеси расчёт налога в отдельную функцию calcTax, поведение
> не меняй. После правки прогони тесты и покажи результат.
> К следующему шагу переходим только если тесты зелёные.Хороший приём — сначала план без правок. В план-режиме Claude раскладывает рефакторинг на шаги и не трогает файлы, пока ты не утвердишь порядок. Это страхует от «снёс полпроекта одним махом». Подробно — в гайде про план-режим Claude Code.
Один шаг — одна правка — один прогон тестов. Скучно и безопасно лучше, чем красиво и сломано.
Коротко
Часть 4 · Разбор
Перед правкой полезно потратить пять минут на разбор. Claude хорош в том, чтобы быстро объяснить незнакомый код: что делает модуль, кто его вызывает, какие у него зависимости и где спрятаны риски. Слепой рефакторинг опасен даже с тестами, потому что тесты ловят не все побочные эффекты.
> Ничего не меняй. Объясни модуль billing.js: что он делает,
> кто его вызывает, от чего зависит, какие места выглядят рискованными
> для рефакторинга. Выдели побочные эффекты (запись в БД, сеть, файлы).Порядок действий
Сначала разбор («объясни, не меняй»), потом сеть из тестов («зафиксируй поведение»), и только потом — маленькие шаги. Этот же подход — разбор незнакомой кодовой базы перед работой — разобран в гайде про отладку с Claude Code: найти корневую причину, а не латать наугад.
Когда рефакторинг лучше отложить
Если кода нельзя покрыть тестами (нет способа проверить поведение) и это критичный прод — рефакторинг откладывают до того, как сеть удастся построить. Не рефакторь то, что не можешь проверить. И не смешивай рефакторинг с новой фичей в одном коммите: разделить «почистил» и «добавил» потом будет невозможно.
Часть 5 · Контроль
Главное
Работай в отдельной ветке и коммить каждый зелёный шаг. Тогда любой неудачный шаг откатывается одной командой, а не героическим разгребанием.
Рефакторинг легаси — это про право на ошибку. Отдельная git-ветка и коммит после каждого зелёного шага дают это право: что-то поехало — вернулся к последнему рабочему состоянию и попробовал иначе. Внутри сессии быстрый откат файлов даёт команда /rewind (откат к чекпойнту), а коммиты страхуют между сессиями.
Весь безопасный git-воркфлоу — ветки, коммиты агента, worktrees для параллельных правок и откат через /rewind — разобран отдельно в гайде про Claude Code и Git. Для рефакторинга это не опция, а обязательная страховка.
Коротко
Вопросы
Рефакторинг — это изменение структуры кода без изменения его поведения: код становится понятнее и чище, но снаружи работает ровно как раньше. Переписывание меняет и поведение, и структуру сразу, и потому опаснее. С Claude Code безопасный путь — именно рефакторинг маленькими шагами, когда после каждого изменения легко проверить, что ничего не сломалось.
Сначала попроси Claude написать тесты на текущее поведение — это страховочная сеть, которая зафиксирует, как код работает сейчас. Потом меняй маленькими шагами и после каждого гоняй тесты. Если тесты зелёные — поведение сохранилось, шаг безопасен. Большую переделку дроби на серию мелких правок: так проще откатить и найти, где именно что-то поехало.
Потому что большую правку невозможно проверить: если в новом коде ошибка, непонятно, где из сотен строк она спряталась. Claude может уверенно выдать неработающий результат, а без сети тестов и мелких шагов ты этого не заметишь. Дробление на шаги — это не перестраховка, а единственный способ удержать контроль над незнакомым кодом.
Хотя бы поверхностно — да, и Claude помогает быстро в нём разобраться: попроси объяснить, что делает модуль, какие у него зависимости и где риски. Слепой рефакторинг без понимания опасен даже с тестами, потому что тесты ловят не всё. Сначала разбор и тесты на текущее поведение, потом аккуратные изменения — в таком порядке.
Читать дальше
Прикладной материал, разборы и рабочие приёмы — то, чем пользуюсь сам, без воды. Залетай, там самое полезное.
Зайти в Telegram