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

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

- **Author:** Фёдор Чищин
- **Published:** 2026-05-17
- **Tags:** agents, methodology, specs
- **Source:** https://fedorthinks.com/ru/blog/specs-are-the-artifact

---

В первый раз, когда я попытался выпустить нетривиального агента, артефакт
на ревью был гигантский 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, либо тихо умирает.
Оба исхода нормальные.

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

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

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

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

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