How to Write a Good Spec for AI Agents

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

Материал технический, но принципы прямо переносятся на работу с ИИ в дизайне: генерация макетов, прототипов, дизайн-систем. По сути, это инструкция по менеджменту ИИ как исполнителя — с чёткими границами, поэтапной приёмкой и встроенным контролем качества. Подход зрелый, опирается на анализ GitHub 2 500+ конфигурационных файлов агентов и практику работы с Claude Code и Gemini CLI.

Главное:

— Начинать с краткого высокоуровневого описания целей и требований, а детализацию поручать самому ИИ. Затем вычитывать сгенерированную спецификацию и фиксировать её как «источник истины» в файле (SPEC.md)

— Использовать режим планирования (Plan Mode) — агент анализирует проект и составляет план, но не пишет код, пока план не утверждён человеком

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

— Границы лучше задавать в три уровня: «делай всегда» (прогоняй тесты перед коммитом), «спроси сначала» (изменение схемы БД, добавление зависимостей), «никогда не делай» (коммит секретов, правка vendor-папок). Самое частое полезное ограничение в исследовании GitHub — «никогда не коммить секреты»

— Один конкретный пример кода в нужном стиле работает лучше трёх абзацев с описанием стиля

— Чем больше инструкций в одном промпте, тем хуже модель следует каждой из них — это подтверждённый исследованиями «curse of instructions». Решение — разбивать работу на модульные задачи и подавать в контекст только релевантную часть спецификации

— Для больших спецификаций полезно создать расширенное оглавление с краткими саммар и каждого раздела. Агент держит в контексте «карту» документа и подгружает детали по мере надобности

— Можно использовать подагентов со своими контекстными окнами и системными промптами: один для базы данных, другой для API, третий для фронтенда. Каждый получает только свою часть спецификации

— Параллельный запуск нескольких агентов на независимых задачах ускоряет работу, но требует чёткого разделения зон ответственности — агенты не должны писать в один и тот же файл

— Встраивать самопроверку: после генерации кода просить агента сверить результат со спецификацией и перечислить невыполненные пункты. Для субъективных критериев (стиль, читаемость) использовать второго агента-ревьюера — паттерн «LLM-as-a-Judge»

— Спецификация — живой документ: обновлять при каждом изменении решений, хранить в системе контроля версий, пересинхронизировать агента после правок

— Антипаттерны: размытые промпты без конкретики, вываливание 50 страниц в контекст без суммаризации, пропуск человеческой ревью, путаница между «vibe coding» (быстрое прототипирование) и продакшн-инженерией

— «Смертельная триада» ИИ-агентов: скорость (работает быстрее, чем успеваешь проверять), недетерминированность (один и тот же ввод — разные результаты) и дешевизна (провоцирует срезать углы на верификации). Процесс ревью должен учитывать все три фактора

— Уровень детализации спецификации должен соответствовать сложности задачи: для тривиальных задач избыточный документ только мешает, для сложных — недостаточный гарантирует провал