Практические заметки: агентный рефакторинг — как агенты помогают высечь скульптуру из кода

Эти заметки восстанавливают практический путь вокруг статьи «Agentic Refactoring — Using Agents to Reveal the Sculpture from Vibe-Coded Rock». Упор сделан на контракты, проверки и места для готового кода, а не на мотивационные речи. На этапе «Обзор» сначала запишите контракт: обязательные входные данные, признак успеха и что происходит при частичном сбое. Такой чек-лист не даст дальнейшим изменениям кода сбиться с курса. Небольшие тестируемые модули лучше разросшихся скриптов. Если шаг падает, сбой должен указывать на одну конкретную ответственность, а не на запутанный конвейер.

Отправная точка

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

Первый срез: абстракции и контракты

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

Создаём абстракцию архитектуры

Этап «Абстракция архитектуры» лучше всего воспринимать как измеримую поверхность. Прежде чем расширять охват, зафиксируйте один эталонный транскрипт, один случай сбоя и заметку об откате. Держите конфигурацию вне кода приложения. Файлы окружения, хранилища секретов и флаги функций должны лежать в одном месте, которое операторы могут проверить, не читая весь граф. Держите состояние графа плоским и типизированным. Вложенные блобы скрывают, какой узел записал какое поле, и ломают возобновление после прерываний. Этап «Абстракция архитектуры» лучше всего воспринимать как измеримую поверхность. Прежде чем расширять охват, зафиксируйте один эталонный транскрипт, один случай сбоя и заметку об откате. Небольшие тестируемые модули лучше разросшихся скриптов. Если шаг падает, сбой должен указывать на одну конкретную ответственность, а не на запутанный конвейер.

Убираем очевидную сложность

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

Тесты мешали

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

Инверсия зависимостей: где она помогла

Для этапа «Инверсия зависимостей: где она помогла» определите входные данные, владельца шага и критерии завершения до того, как менять код. Операторы должны иметь возможность перезапустить шаг с известной контрольной точки, не гадая о скрытом состоянии. Держите конфигурацию вне кода приложения. Файлы окружения, хранилища секретов и флаги функций должны лежать в одном месте, которое операторы могут проверить, не читая весь граф. Ставьте подтверждение человеком на переходах, которые тратят деньги или меняют данные в продакшене. То, что всё связано на этапе компиляции, ещё не значит, что бизнес-задача решена полностью. Для этапа «Инверсия зависимостей: где она помогла» определите входные данные, владельца шага и критерии завершения до того, как менять код. Операторы должны иметь возможность перезапустить шаг с известной контрольной точки, не гадая о скрытом состоянии. Небольшие тестируемые модули лучше разросшихся скриптов. Если шаг падает, сбой должен указывать на одну конкретную ответственность, а не на запутанный конвейер.

Проявляем доменную модель

На этапе «Проявляем доменную модель» сначала запишите контракт: обязательные входные данные, признак успеха и что происходит при частичном сбое. Такой чек-лист не даст дальнейшим изменениям кода сбиться с курса. Относитесь к этому этапу как к контракту между входными данными и проверенным результатом. Назовите артефакты, задайте проверки успеха и не допускайте тихого частичного выполнения. Кэшируйте стабильные системные инструкции и схемы инструментов. Повторная отправка одной и той же преамбулы — частая причина лишних расходов.

Как работать с командой агентов

На этапе «Как работать с командой агентов» сначала запишите контракт: обязательные входные данные, признак успеха и что происходит при частичном сбое. Такой чек-лист не даст дальнейшим изменениям кода сбиться с курса. Записывайте время выполнения и стоимость в токенах или запросах рядом с функциональными результатами. Если стоимость видна с самого начала, не будет неожиданных счетов, когда решение переедет из демо в общие окружения. Ставьте контрольную точку после дорогих шагов. Возобновление не должно заново оплачивать тот же вызов LLM, когда оператор перезапускает более поздний узел.

Архитектура наконец стала видна

На этапе «Архитектура наконец стала видна» сначала запишите контракт: обязательные входные данные, признак успеха и что происходит при частичном сбое. Такой чек-лист не даст дальнейшим изменениям кода сбиться с курса. Держите конфигурацию вне кода приложения. Файлы окружения, хранилища секретов и флаги функций должны лежать в одном месте, которое операторы могут проверить, не читая весь граф. Ставьте контрольную точку после дорогих шагов. Возобновление не должно заново оплачивать тот же вызов LLM, когда оператор перезапускает более поздний узел. На этапе «Архитектура наконец стала видна» сначала запишите контракт: обязательные входные данные, признак успеха и что происходит при частичном сбое. Такой чек-лист не даст дальнейшим изменениям кода сбиться с курса. Небольшие тестируемые модули лучше разросшихся скриптов. Если шаг падает, сбой должен указывать на одну конкретную ответственность, а не на запутанный конвейер.

Как создавалась эта статья

Этап «Как создавалась эта статья» лучше всего воспринимать как измеримую поверхность. Прежде чем расширять охват, зафиксируйте один эталонный транскрипт, один случай сбоя и заметку об откате. Относитесь к этому этапу как к контракту между входными данными и проверенным результатом. Назовите артефакты, задайте проверки успеха и не допускайте тихого частичного выполнения. Держите состояние графа плоским и типизированным. Вложенные блобы скрывают, какой узел записал какое поле, и ломают возобновление после прерываний.

Операционный чек-лист

Для этапа «Операционный чек-лист» определите входные данные, владельца шага и критерии завершения до того, как менять код. Операторы должны иметь возможность перезапустить шаг с известной контрольной точки, не гадая о скрытом состоянии.

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

Ставьте подтверждение человеком на переходах, которые тратят деньги или меняют данные в продакшене. То, что всё связано на этапе компиляции, ещё не значит, что бизнес-задача решена полностью.

Напишите короткий ранбук: как ротировать ключи, как опустошить очередь, как откатить последнюю загрузку.

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

Ставьте подтверждение человеком на переходах, которые тратят деньги или меняют данные в продакшене. То, что всё связано на этапе компиляции, ещё не значит, что бизнес-задача решена полностью.

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

Заметка по партии 2e4d73bb1bc8: держите ключи провайдеров вне репозитория, задайте потолок токенов на сессию и храните транскрипты рядом с фикстурами для оценки, чтобы при будущей смене модели результаты можно было сравнить.