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

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

Відправна точка

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

Перший зріз: абстракції та контракти

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

Створюємо абстракцію архітектури

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

Прибираємо очевидну складність

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

Тести заважали

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

Інверсія залежностей: де вона допомогла

Для етапу «Інверсія залежностей: де вона допомогла» визначте вхідні дані, власника кроку й критерії завершення ще до зміни коду. Оператори повинні мати змогу перезапустити крок із відомої контрольної точки, не вгадуючи прихований стан. Тримайте конфігурацію поза кодом застосунку. Файли середовища, сховища секретів і прапорці функцій мають лежати в одному місці, яке оператори можуть перевірити, не читаючи весь граф. Ставте підтвердження людиною на переходах, які витрачають гроші або змінюють дані в продакшені. Те, що все зв'язано на етапі компіляції, ще не означає, що бізнес-завдання розв'язано повністю. Для етапу «Інверсія залежностей: де вона допомогла» визначте вхідні дані, власника кроку й критерії завершення ще до зміни коду. Оператори повинні мати змогу перезапустити крок із відомої контрольної точки, не вгадуючи прихований стан. Невеликі модулі, які можна протестувати, кращі за розрослі скрипти. Якщо крок падає, збій має вказувати на одну конкретну відповідальність, а не на заплутаний конвеєр.

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

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

Як працювати з командою агентів

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

Архітектура нарешті стала видимою

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

Як створювалася ця стаття

Етап «Як створювалася ця стаття» найкраще сприймати як вимірювану поверхню. Перш ніж розширювати охоплення, зафіксуйте один еталонний транскрипт, один випадок збою і нотатку про відкат. Ставтеся до цього етапу як до контракту між вхідними даними й перевіреним результатом. Назвіть артефакти, задайте перевірки успіху й не допускайте тихого часткового виконання. Тримайте стан графа пласким і типізованим. Вкладені блоби приховують, який вузол записав яке поле, і ламають відновлення після переривань.

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

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

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

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

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

Невеликі модулі, які можна протестувати, кращі за розрослі скрипти. Якщо крок падає, збій має вказувати на одну конкретну відповідальність, а не на заплутаний конвеєр.

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

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

Нотатка щодо партії 2e4d73bb1bc8: тримайте ключі провайдерів поза репозиторієм, задайте стелю токенів на сесію і зберігайте транскрипти поруч із фікстурами для оцінювання, щоб після майбутньої заміни моделі результати можна було порівняти.