К содержимому
Блог

Claude Code на легаси: порядок работы с кодом без документации

Claude Code на легаси: порядок работы с кодом без документации

Claude Code в легаси полезен как исследователь и исполнитель маленьких изменений. Просьба «отрефактори модуль» в незнакомом проекте обычно выдаёт широкий дифф без доказательства безопасности. Более надёжный маршрут начинается с чтения, фиксирует текущий сценарий тестом и ограничивает каждую правку понятной границей.

Коротко

  • Первый проход строит карту вызовов и зависимостей, но не меняет файлы.

  • Тест сначала описывает существующее поведение, даже если оно выглядит странно.

  • Маленький дифф легче проверить, откатить и объяснить на ревью.

С чего начать разбор легаси с Claude Code

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

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

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

Как составить карту рисков

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

В легаси особенно опасны удаления. Условие, которое кажется мёртвым, иногда защищает старую интеграцию или повторный запрос. Попросите агента перечислить строки на удаление и назвать путь, где каждая из них ещё может сработать. Если он не может это доказать, оставьте код до отдельного исследования.

Как зафиксировать текущее поведение

Тест пишут против неизменённой ветки. Он описывает не желаемый результат, а то, что система делает сейчас в выбранном сценарии. Так команда получает базовую точку: если тест проходит до правки и падает после, изменение действительно затронуло поведение.

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

Почему правки лучше дробить

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

Хорошая последовательность выглядит так: карта, тест, правка, проверка, следующий тест. Плохая: массовая замена, удаление «лишнего», новый интерфейс и попытка объяснить всё в одном PR. Агент способен предложить оба варианта. Выбор порядка остаётся за разработчиком.

Контекст тоже имеет цену. Сохраняйте карту в документе проекта и в следующей сессии открывайте только нужные части. Общие способы контроля запросов и лимитов собраны в документации API.

Как вести диалог с агентом

Формулируйте вопрос так, чтобы ответ можно было оспорить. Вместо «этот код можно удалить?» спросите, какие вызовы доходят до ветки, как это проверить и какой сценарий она защищает. Вместо «покрой тестами» попросите назвать один сценарий, который проходит до изменения и должен пройти после него.

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

Где заканчивается задача агента

Агент помогает найти следы, подготовить тест и сделать небольшой дифф. Он не должен единолично принимать решение о совместимости внешнего API, изменении финансовой логики или удалении старой миграции. Такие границы лучше записать в инструкции проекта до старта работы.

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

Можно ли поручить агенту полную переработку старого модуля?

Можно, если сначала разделить работу на исследование и небольшие проверяемые изменения. Без карты зависимостей широкий запрос приводит к диффу, который трудно проверить. Начните с одного сценария, сохраните результат разведки и только затем расширяйте область.

Что делать, если в проекте нет тестов?

Сделайте первым изменением минимальный тест текущего поведения вокруг нужной границы. Он не обязан покрыть весь модуль. Его задача показать, что вы поняли конкретный путь до начала рефакторинга и сможете заметить непреднамеренное изменение.

Как понять, что агент не удалил важную ветку?

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

Подключить Claude Code к Relay

Готовы подключиться?Войдите в консоль, пополните баланс и создайте API-ключ.