AGENTS · 17 мая 2026 г.

Артефакт — это спецификация, а не промпт

Когда поведение агента приходит через PR со спецификацией, а не через правку промпта, команда рассуждает об агентах так же, как о коде. Как это выглядит на практике и почему работает.

В первый раз, когда я попытался выпустить нетривиального агента, артефакт на ревью был гигантский system prompt: шесть параграфов, список инструментов, несколько примеров диалога и список «нельзя», который рос каждый раз, когда что-то ломалось. Ревьюеры комментировали прозу. Новое поведение приходило правкой промпта — иногда в PR, иногда вставкой в Slack. На вопрос что вообще должен делать этот агент? не было единого источника of truth.

Это не масштабируется дальше одного агента.

Как выглядит спецификация

Спецификация — единый артефакт под version control для одного агента. В ней:

Identity: имя, роль, за что отвечает в одной фразе.
System prompt: реальный промпт, как он рендерится. Со ссылками на каноничные инструкции, общие с другими специями.
Tool list: каждый инструмент, который агент может вызвать, с контрактом, который обеспечивает MCP-сервер. Никаких «магических» tools.
Guardrails: что агент обязан отказаться делать. Конкретно, тестируемо.
Output schema: форма structured output, валидируется на границе. Свободный текст — только когда потребитель — пользователь.
Evaluations: какие сценарии этот агент обязан проходить. Публичные benchmarks плюс holdout-набор.

Ревьюеры утверждают спецификацию. Runtime генерируется из неё.

Что меняется

Три вещи, все важные.

Ревью про поведение, а не про формулировки. «Сделай агента более полезным» перестаёт быть полезным комментарием в PR. Разговор становится: «не хватает guardrail», или «этого tool нет в списке — должен быть?», или «output schema не покрывает пустой случай». О чём-то конкретном теперь можно не соглашаться.

Улучшения накапливаются. Каждый prompt tweak, который кто-то выпустил через Slack в прошлом квартале, теперь либо в спецификации, либо нет. Если нет — он либо заново выводится из first principles, либо тихо умирает. Оба исхода нормальные.

Онбординг — это директория. Новый инженер читает четыре спецификации и знает что делает система. Не читает обрывки промптов из двенадцати файлов.

Где сложнее чем звучит

Спеки не бесплатны. Три честные цены:

Нужен tool-слой. Если агент дёргает httpx.get(...) инлайн, у спецификации нет дисциплины, которую можно обеспечить. Спецификация предполагает, что инструменты типизированы, версионированы и discoverable. MCP ложится.
Нужен реальный eval suite. Без него спецификация — просто оптимистичная проза. Eval делает её контрактом.
Нужно написать спецификацию. Эта часть ощущается бюрократией ровно до момента когда второй агент уходит в production.

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