2500 репозиториев, 5 принципов: гайд инженера Google по AI-агентам

Эдди Османи, инженер Google Cloud и Gemini, опубликовал подробный гайд по написанию спецификаций для AI-агентов. В основе — анализ более 2500 конфигурационных файлов агентов на GitHub и собственный опыт работы с Claude Code и Gemini CLI. Главный вывод: огромный промпт со всеми требованиями не работает — у моделей ограничен "бюджет внимания", и после определённого порога они начинают игнорировать часть инструкций.

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

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

Османи предлагает начинать с высокоуровневого видения и позволять агенту самому расширить его в детальный план — сначала в режиме "только чтение", без генерации кода. Спецификация при этом становится живым документом: ее нужно обновлять по мере работы и использовать как единый источник правды для всех сессий. Для сложных проектов автор рекомендует разделять контекст между несколькими субагентами со своими специализациями — например, один отвечает за базу данных, другой за API, третий за фронтенд.

Отдельный блок гайда посвящен самопроверкам. Османи советует встраивать в спецификацию инструкции, по которым агент сам проверяет результат: "После реализации сверься со спекой и подтверди, что все требования выполнены". Для субъективных критериев — читаемости кода, соответствия архитектуре — можно использовать паттерн LLM-as-a-Judge: второй агент ревьюит вывод первого. Не менее важно вкладывать в спеку собственную экспертизу: подводные камни библиотек, неочевидные edge-кейсы, предпочтения по стилю. Все, что знаешь только ты, — должно быть в документе.

Наконец, Османи подчеркивает итеративность: тестировать рано, после каждого открытия обновлять спеку, не ждать финала. В гайде он цитирует Саймона Уиллисона, который сравнил работу с AI-агентами с "очень странной формой менеджмента" и "управлением интерном, который точно будет халтурить, если дать ему шанс". Спецификация в этой модели — инструмент контроля: она задает границы, включает самопроверки и не даёт агенту отклониться от задачи.

P.S. Поддержать меня можно подпиской на канал "сбежавшая нейросеть", где я рассказываю про ИИ с творческой стороны.