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» (быстрое прототипирование) и продакшн-инженерией

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

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

How Product Discovery changes with AI

Дэвид Хоанг (ex-One Medical, ex-Webflow) разобрал, как ИИ меняет процесс продуктового дискавери: три из четырёх классических рисков — реализуемость, жизнеспособность и юзабилити — резко дешевеют, а главным дифференциатором становится desirability, то есть понимание того, нужен ли продукт людям вообще.

Статья — личное эссе практика с конкретными примерами из собственных проектов. Хоанг не теоретизирует, а описывает, как уже работает: прототипирует в продакшене за часы, собирает фидбек на реальных данных и пивотит до запуска. Подход спорный в части «прототип сразу в прод» — не каждая команда может себе это позволить, — но сам сдвиг фокуса с «можем ли построить» на «стоит ли это существовать» точно стоит внимания.

Главное:

— Продуктовый дискавери строится вокруг четырёх рисков: desirability (хотят ли это), viability (работает ли для бизнеса), feasibility (можем ли построить), usability (смогут ли пользоваться)

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

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

— Когда три риска дешевеют, оставшийся — desirability — становится конкурентным преимуществом. Главный вопрос сменился с «Можем ли мы это построить?» на «Должно ли это существовать?»

— Хоанг по-прежнему начинает с ручки и бумаги, но бумажный скетч больше не показывает людям — вместо этого «скетчит кодом» на разных уровнях детализации: от простой HTML-страницы с захардкоженными данными до прототипа с реальными API

— Прототипирование сместилось из стейджинга в продакшен. Свой проект Tapestry (CRM с ИИ) Хоанг собрал за несколько часов в Replit, задеплоил, дал реальным пользователям — и по результатам фидбека пивотнул архитектуру

— Продакшен-прототип ≠ запуск продукта. Это может быть закрытая бета — просто более честная среда для тестирования, чем стейджинг. С ИИ можно пивотнуть десятки раз до выхода на рынок, а не после

— Инструменты с «виртуальными персонами» Хоанг не использует для первичного исследования. Сложность никогда не была в синтезе находок — сложно получить правильные инсайты изначально

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