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 хорош не тогда, когда выглядит внушительно, а тогда, когда его можно открыть, понять, применить и по его результату принять решение. И как только вы начинаете смотреть на инструкции именно так, агент перестаёт быть загадочным существом и становится вполне земным рабочим инструментом — аккуратным, ограниченным и полезным.