17 мая 2026 г.

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

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

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

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

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

Спека — единый source-controlled артефакт на одного агента. В ней:

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.

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