Як налагоджувати AI-агентів, що змінюють не те, що потрібно: Доказовий підхід

Проблема "Виправлено" без доказів

При роботі з AI-агентами для кодування, найскладніше не завжди написати код. Складність полягає в тому, щоб показати, що агент зрозумів запит, змінив правильне місце та перевірив правильний результат. Агент може виконати кілька дій під час виконання, але все одно завершити роботу короткою відповіддю, наприклад, «виправлено». Ця відповідь приховує важливі деталі: що саме було перевірено, що змінено, що запущено і що довело ефективність виправлення. Без таких доказів неможливо визначити, чи відповідає остаточна перевірка початковій скарзі користувача.

Цей пробіл проявляється у звичайних запитах на кодування. Прохідна збірка може показати, що програма все ще компілюється, навіть якщо кнопка залишається неробочою. Прохідний тест може означати, що твердження стало слабшим. Правдоподібна зміна маршруту все ще може пропустити обробник, який надає відповідь. Агент кодування повинен змінювати код і доводити, що він перевірив, що змінив, що запустив і який результат зробив виправлення прийнятним.

Трасування та Протокол Контексту Моделі

Програмна інженерія вже має назву для частини цієї проблеми: трасування (traceability). Трасування вимог описується як здатність відстежувати вимогу від її виникнення до її виконання. У роботі з агентами кодування та ж ідея стає більш безпосередньою: чи можете ви пов'язати запит користувача з перевіреними файлами, застосованим патчем, результатом команди та остаточною перевіркою?

Протокол Контексту Моделі (Model Context Protocol, MCP) описує стандартний спосіб для додатків штучного інтелекту підключатися до файлів, інструментів, джерел даних та інших зовнішніх систем. Цей стандарт допомагає лише в тому випадку, якщо виконання інструменту залишає докази, які розробник може переглянути.

Приклад: Виправлення UI-багу

Посібник розглядає проблему, з якою стикаються як розробники, так і «вайб-кодери»: агент щось змінює, звучить впевнено, і залишає вас гадати, чи торкнувся він правильної частини програми. Приклад використовує баг інтерфейсу користувача, оскільки візуальні виправлення легко зробити неправильно і легко перевірити в браузері. Картка ціноутворення має основну кнопку, яка виходить за межі екрана на мобільних пристроях. Виправлення — це цільова зміна Cascading Style Sheets (CSS).

Корисна частина полягає у збережених доказах навколо виправлення: читання файлів, спроба неправильного селектора, виявлена перевіркою браузера, цільовий патч, вивід збірки, вимірювання Document Object Model (DOM) та скріншоти до і після. Це дозволяє створити шаблон перевірки, який можна адаптувати до поширених збоїв агентів кодування: неправильний файл, неправильний селектор, неправильна функція, пропущена команда, відредагований тест, зламаний маршрут, пропущений граничний випадок або виправлення, яке проходить одну перевірку, але не відповідає фактичному запиту користувача.

Що має довести агент?

Корисний запуск агента кодування повинен відповідати на п'ять питань:

• Які файли перевірив агент?
• Який селектор або компонент він ідентифікував як цільовий?
• Який саме патч він застосував?
• Чи все ще збиралася програма?
• Чи правильна перевірка довела, що повідомлена проблема змінилася?

Це суворіше, ніж просто запитувати diff. Diff — це вигляд змін коду до і після. Він може виглядати розумно, навіть якщо сторінка все ще неправильна. Скріншот може показати, що цільова кнопка виправлена, приховуючи, що інший компонент зламався. Прохідна збірка лише доводить, що програма скомпілювалася. Вона не доводить, що інтерфейс користувача все ще виглядає правильно. Для роботи агента кодування остаточна відповідь повинна бути підсумком доказів, а не заявою про успіх.

Налаштування Інструментів та Запис Дій

Скрипт на Python обгортає цикл інструментів моделі за допомогою записувача. Модель може запитувати інструмент. Python вирішує, чи існує цей інструмент, запускає відповідну функцію та зберігає як запит, так і результат у журналі виконання. Ця обгортка є корисною ідеєю. Якщо ви хочете знати, що ваша модель робила під час завдання кодування, записуйте запити інструментів моделі та реальні результати функцій навколо них.

Скрипт надає моделі такі вузькі інструменти, які ви б виставили через сервер MCP:

• list_files: Перелічує відповідні файли програми, запобігаючи сліпим редагуванням.
• read_file: Читає один файл за раз, роблячи перевірений контекст видимим.
• apply_patch: Застосовує цільовий CSS-патч, зберігаючи зміни придатними для перегляду.
• run_build: Запускає npm run build, виявляючи зламану структуру програми.
• inspect_dom: Відкриває програму в Chromium та вимірює цільовий елемент, перевіряючи відрендерений елемент.
• capture_screenshot: Зберігає скріншот браузера, надаючи візуальні докази.

MCP має значення тут, оскільки він може упаковувати ці функції інструментів для різних клієнтів агента. Основна ідея все ще практична: модель запитує інструмент, програма перевіряє та запускає його, а журнал виконання записує як запит, так і результат.

Існуючі Рішення та Їх Обмеження

Існують інструменти, які вже відстежують виклики моделей, виклики інструментів, витрати, затримки та помилки. Серед них Weights & Biases Weave, LangSmith, Arize Phoenix та Langfuse. Також є інструменти, спрямовані безпосередньо на агентів кодування, такі як Dynatrace та Arize, які описують моніторинг агентів кодування за запитами LLM, виконанням інструментів, знімками файлів та операціями diff.

Ці інструменти корисні, коли команда бажає мати розміщені трасування, інформаційні панелі, пошук, відстеження витрат або оцінку в масштабі. Проте, пробіл полягає в тому, як обгорнути одне кероване моделлю завдання кодування, щоб розробник міг бачити точні запити інструментів, зміни файлів, перевірки, скріншоти (за потреби) та збої, які призвели до остаточного виправлення. Цей самий журнал виконання можна пізніше надіслати до Weave, LangSmith, Phoenix або Langfuse. Перший крок — переконатися, що журнал виконання записує правильні речі.

Практичний Посібник

Для демонстрації використовується супутній репозиторій GitHub: abduldattijo/coding-agent-run-recorder. Він містить структуру файлів, включаючи ui_fixing_agent.py, app/ з HTML, CSS та JavaScript, а також скрипти для перевірки збірки та інспекції UI. Для запуску потрібні Python 3.10 або новіший, Node.js та npm, браузер Playwright Chromium та ключ API OpenAI.

Запуск скрипта ui_fixing_agent.py у режимі API дозволяє моделі вибирати наступний виклик інструменту. Режим відтворення (--mode replay) дозволяє відтворити ті ж функції інструментів у тому ж порядку без використання ключа API. Кожне твердження походить із зафіксованих доказів виконання.

Наприклад, перевірка браузера використовує Playwright для відкриття сторінки з певним розміром вікна (390 x 844), знаходить цільову картку та кнопку та порівнює їхні обмежувальні рамки. Це доводить конкретний збій, описаний у запиті: цільова кнопка більше не виходить за межі картки на вибраному мобільному вікні перегляду.

Журнал виконання зберігається у файлі outputs/ui_fixing_agent_run_log.json. Він записує повний ланцюжок: запити моделі, результати функцій (наприклад, restore_baseline, list_files, read_file, inspect_dom before_fix, apply_patch wrong selector, inspect_dom wrong_selector_attempt, apply_patch target button, run_build, inspect_dom after_fix). Без журналу виконання розробник бачить лише кінцевий код. З журналом розробник може перевірити запитані дії моделі та результати функцій, які за ними слідували.

Адаптація до Власних Завдань

Картка ціноутворення — це лише приклад. Шаблон, який можна використовувати повторно, такий:

1. Нечіткий запит на кодування.
2. Прочитати ймовірні файли.
3. Ідентифікувати цільову поведінку.
4. Запустити перевірку, яка показує зламаний стан.
5. Застосувати вузький патч.
6. Запустити збірку.
7. Знову запустити ту ж перевірку.
8. Зберегти журнал виконання, diff, JSON та скріншоти.

По-перше, змініть інструменти. Залиште read_file, apply_patch та run_build, але замініть inspect_dom на перевірку, яка відповідає вашому багу. Для багу API це може бути call_endpoint. Для збою тесту — run_test. Для зміни бази даних — run_migration_check.

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

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

Що це означає для розробників

Ця новина означає для розробників можливість отримати прозорість та довіру до роботи AI-агентів. Вона надає шаблон для перевірки дій агента, дозволяючи переконатися, що зміни були правильними та підтвердженими, а не просто прийняти відповідь «виправлено». Це допомагає виявляти помилки, такі як зміни не в тому місці або ослаблення тестів.

Ключові факти

• AI-агенти часто надають відповідь «виправлено» без детальних доказів своїх дій, що ускладнює перевірку правильності змін.

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

• Протокол Контексту Моделі (MCP) може стандартизувати підключення AI-додатків до зовнішніх систем, сприяючи збору доказів.

• Корисний запуск агента має відповідати на п'ять питань: які файли перевірено, який елемент цільовий, який патч застосовано, чи зібралася програма, чи підтверджено виправлення.

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

Джерела

• How to Debug AI Coding Agents When They Change the Wrong Thing