Engineering contract в інструкції агента

1. Інструкція замість персонажа

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

Модель добре реагує на роль, але ще краще — на межі. Задасте характер — отримаєте характер. Задасте контракт — отримаєте результат. Гарний тон проти передбачуваної поведінки.

Порівняйте два варіанти.

Поганий варіант:
Ти дуже досвідчений code reviewer. Думай як senior engineer,
перевіряй код глибоко й уважно, знаходь усе важливе.

Така інструкція не відповідає ані на одне важливе запитання. Коли саме запускати агента? Що вважати результатом? Де зупинитися? Ні меж, ні формату, ні стоп-сигналів.

Тепер подивіться на підхід із контрактом.

Гарний вектор:
Роль: reviewer для готового diff.
Коли використовувати: після того, як зміна готова до перевірки.
Дозволено: читати diff, тести та повʼязані файли; повернути findings з evidence.
Зупинитися: якщо diff занадто великий або зачіпає чутливі зони.

Друга версія не така літературна, зате з нею вже можна працювати. Інший розробник зрозуміє, чого чекати. Claude стабільніше делегує. А результат ви приймаєте або відхиляєте за форматом, не за інтуїцією.

2. Чотири елементи робочого контракту

Щоб інструкція не розповзалася в нескінченний трактат, корисно тримати перед очима просту рамку з чотирьох елементів. Цього мінімуму вистачає для передбачуваного агента. Без цих чотирьох частин агент — «ніби розумний, але якийсь слизький».

Нижче — опорна таблиця, на яку можна дивитися як на креслення.

Якщо хочете коротку формулу, вона виглядає так:

Інструкція агента = роль
                  + коли використовувати
                  + дозволені дії та формат результату
                  + умови зупинки

Це і є той самий engineering contract. Не біографія. Не маніфест. Не «поведінковий портрет ідеального колеги». Контракт.

3. Роль: одна фраза, що відтинає зайве

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

Роль має бути настільки вузькою, щоб її можна було вимовити однією фразою й одразу зрозуміти призначення. Для нашого артефакту Workflow Kit хороший приклад такий: «AI-assisted reviewer для перевірки готового diff». Тут уже ясно, що агент не займається реалізацією, не шукає архітектуру для нового модуля, не лагодить тести, а саме перевіряє вже зроблену зміну.

Добре працює простий прийом: спробуйте підставити роль у фразу «Я запускаю цього агента, коли мені потрібен…». Якщо виходить чіткий зміст, роль сформульовано вдало. Якщо виходить щось туманне на кшталт «коли мені потрібен розумний погляд на проєкт», значить, роль ще не заземлено.

Слабка роль:
Ти технічний експерт із якості коду.

Сильна роль:
Ти reviewer для готового PR/diff у проєкті.

У другому варіанті агент уже не вдає із себе всемогутнього. І це дуже добре. Хороший агент не має бути всемогутнім. Він має бути корисним в одній конкретній роботі.

4. Тригер «коли використовувати»

Тут студенти часто думають: «Але ж у нас уже є description у frontmatter. Навіщо ще раз пояснювати, коли використовувати агента?» Запитання чудове. Різниця в тому, що description — це коротка вивіска на вхідних дверях. Вона допомагає Claude зрозуміти, якого помічника взагалі вибрати. А розділ «Коли використовувати» всередині інструкції — це вже робоче правило і для моделі, і для людини, яка супроводжує цей файл.

Простіше кажучи, description відповідає за вибір агента ззовні, а розділ «Коли використовувати» — за дисципліну його застосування зсередини.

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

Поганий варіант:
Коли потрібно перевірити код.

Кращий варіант:
Використовувати після того, як зміна готова до локальної перевірки:
є diff, зрозумілий scope, за можливості запущені повʼязані тести.
Не використовувати для написання коду або для дослідження з нуля.

Зверніть увагу, що в хорошому варіанті є не лише «коли так», а й легке «коли ні». Це корисно. Чітка інструкція часто виграє не від великої кількості дозволів, а від кількох розумних заборон. Без них агент починає чіплятися до невідповідних сценаріїв. А потім створюється враження, що «агент якийсь дивний». Насправді дивний не агент, а неясний тригер запуску.

5. Дії та формат результату

Ось тут інструкція перестає бути просто текстом і стає інженерним інструментом. Бо саме в цьому розділі ви відповідаєте на два запитання: що агенту дозволено робити і в якому вигляді він зобовʼязаний повернути результат. Якщо не прописати це явно, агент майже напевно почне імпровізувати. А імпровізація хороша у стендапі, але не дуже хороша в code review.

Для reviewer-агента типова рамка така: він може читати diff, повʼязані файли та тести, за потреби виконувати безпечні read-only перевірки, а на виході зобовʼязаний повернути findings за severity з доказами. Тобто не просто «мені здається, тут щось не так», а «файл такий-то, рядок такий-то, ось чому це ризик, ось що варто перевірити».

Дуже корисно одразу вбудовувати у формат результату маркування гіпотез. Наприклад, якщо агент підозрює проблему, але не може її довести, він має так і написати: [hypothesis]. Це проста дрібниця, але вона сильно дисциплінує висновок. І модель, і людина перестають видавати здогад за встановлений факт.

Приклад мінімального формату результату може виглядати так:

Формат результату:
- Короткий summary
- Findings:
  - severity
  - file:line
  - evidence
  - suggested action
- Open questions

А тепер — шматок більш конкретної інструкції для reviewer.

## Дозволені дії та формат результату
- Читати diff, зачеплені файли та повʼязані тести.
- Перевіряти відповідність change scope заявленому завданню.
- Повернути findings за важливістю: high / medium / low.
- Для кожного findings указувати file:line і evidence.
- Якщо доказів недостатньо, позначати висновок як [hypothesis].
- Не редагувати код.

Зверніть увагу, тут одночасно зашито і поведінку, і структуру відповіді. Це зручно. Бо потім, коли агент поверне результат, ви зможете дуже швидко зрозуміти: він узагалі впорався із завданням чи ні. Якщо файл і рядок не вказані, evidence немає. Якщо severity немає, findings незручно читати. Якщо всі підозри подаються як факти, агента треба переписати. Усе прозоро.

6. Умови зупинки агента

Це, мабуть, найбільш недооцінений розділ. Новачки часто думають, що хороший агент має «дотягувати завдання до кінця». На практиці саме через це і починається хаос. Агент із неописаними стоп-умовами схильний продовжувати роботу навіть тоді, коли вже давно потрібно повернути керування людині. Він бачить великий diff — і продовжує. Він заходить у чутливу зону на кшталт payments/ — і продовжує. Йому бракує evidence — і він усе одно пише впевнений висновок. Не зі шкідливості. Просто його ніхто вчасно не навчив зупинятися.

Умови зупинки — це не слабкість агента. Це його зрілість. Вони дають змогу зберегти передбачуваність і не перетворювати review на приховану реалізацію або на потік бездоказових порад.

Для reviewer-агента умови зупинки зазвичай привʼязані до розміру diff, чутливості області та нестачі доказів. Наприклад: якщо diff занадто великий, попросити розбити зміну на частини; якщо зачеплено auth, payments, migrations або інші чутливі зони, не робити сміливих висновків без додаткової перевірки; якщо немає тестів або evidence недостатньо, явно повернути open questions замість упевненого verdict.

## Умови зупинки
- Якщо diff занадто великий для осмисленого review, повернути прохання звузити scope.
- Якщо зміна зачіпає чутливі зони, не робити сильних висновків без evidence.
- Якщо перевірка впирається в нестачу даних, повернути open questions.
- Після видачі findings передати рішення людині.

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

7. Збірка agents/reviewer.md для Workflow Kit

Тепер давайте зберемо все в один артефакт, який справді міг би лежати в нашому Workflow Kit і допомагати команді під час роботи з Commerce OS. Уявіть, що у вас є PR із виправленням дублювання замовлень у списку /api/orders або з коригуванням сортування refund-запитів. Зміна вже зроблена, diff готовий, тести хоча б частково прогнані. Саме час для reviewer-агента.

Нижче вже не стартова заготовка, а перший робочий варіант reviewer-а, на який далі можна спиратися як на базовий командний контракт.

Точні назви tool IDs і capability names залежать від поточного інтерфейсу /agents. Тут важливий не буквальний список ідентифікаторів, а те, що reviewer залишається read-only і отримує лише те, що потрібно для читання diff і пошуку evidence. Перевіряйте доступні назви в поточному UI або docs.

Зовні файл може починатися так:

---
name: reviewer
description: AI-assisted reviewer for ready PR diffs. Read-only. Use for local review before human decision.
tools: [read, grep, diff]
---

А далі йде тіло інструкції, уже у форматі контракту:

## Роль
Ти reviewer для готового diff у проєкті.

## Коли використовувати
Використовувати після того, як зміна готова до локальної перевірки:
є diff, зрозумілий scope, за можливості запущені повʼязані тести.

## Дозволені дії та формат результату
Читай diff, повʼязані файли та тести.
Поверни summary, findings за важливістю та open questions.
Для кожного findings укажи file:line і evidence.
Гіпотези без доказів позначай як [hypothesis].
Код не редагуй.

## Умови зупинки
Якщо diff занадто великий або зачіпає чутливі зони,
не роби широких висновків і попроси звузити scope або дати більше evidence.
Після findings передай рішення людині.

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

Дуже корисний мисленнєвий тест: відкрийте цей файл так, ніби ви нова людина в команді й бачите його вперше. Чи можете ви за хвилину зрозуміти, коли агента викликати, чого від нього чекати і чого він точно не має робити? Якщо так, файл уже живий. Якщо ні, значить, інструкцію поки написано більше «для автора», ніж для системи та команди.

8. Ознаки робочої інструкції

Є простий спосіб перевірити якість інструкції без складних метрик. Спробуйте відповісти на чотири запитання. По-перше, чи зрозуміло з файла, у який момент агент взагалі потрібен. По-друге, чи зрозуміло, який результат він зобовʼязаний повернути. По-третє, чи видно, що йому заборонено робити. І, нарешті, по-четверте, чи ясно, у який момент він зобовʼязаний зупинитися й повернути керування людині.

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

Корисно також памʼятати різницю між tools і тілом інструкції. tools відповідають на запитання «що агент фізично може». Інструкція відповідає на запитання «як він має цим користуватися». Це різні рівні. Якщо у вас ідеально обмежено інструменти, але розпливчаста інструкція, агент усе одно хитатиметься в межах дозволеної кімнати. Якщо інструкція чудова, але інструменти видано занадто широко, він усе одно одного дня впирається лобом у зайву владу. Потрібні обидві частини.

І ще один важливий практичний момент. Не намагайтеся зробити ідеальну інструкцію з першої спроби. Набагато краще випустити робочу, зрозумілу версію, запустити її на кількох реальних review-сценаріях і подивитися, де вона «тече». Може виявитися, що агент занадто часто пише бездоказові висновки — отже, треба посилити evidence requirement. Може зʼясуватися, що він лізе в реалізацію і пропонує переписати пів модуля — отже, треба жорсткіше прописати межі ролі й stop conditions. Такі файли ростуть не від натхнення, а від спостереження за збоями.

У підсумку у вас виходить не «розумний текст про AI», а підтримуваний інженерний артефакт. Саме це нам і потрібно у Workflow Kit. Файл agents/reviewer.md хороший не тоді, коли виглядає вражаюче, а тоді, коли його можна відкрити, зрозуміти, застосувати й за його результатом ухвалити рішення. І щойно ви починаєте дивитися на інструкції саме так, агент перестає бути загадковою істотою і стає цілком земним робочим інструментом — акуратним, обмеженим і корисним.