- Инженер Google Эдди Османи проанализировал более 2500 конфигурационных файлов AI-агентов на GitHub и разработал гайд по написанию их спецификаций.
- Основная рекомендация — разбивать задачи на модули и избегать избыточных инструкций в одном промпте из-за ограничений «бюджета внимания» моделей.
- Спецификации должны включать шесть ключевых разделов, быть живыми документами с самопроверками и обновлениями во время работы.
Инженер Google Cloud и Gemini Эдди Османи опубликовал подробное методическое руководство по созданию спецификаций для искусственных интеллект-агентов. В своей работе он опирается на анализ свыше 2500 публичных репозиториев на GitHub, а также на собственный опыт работы с системами Claude Code и Gemini CLI. Главная проблема, отмеченная экспертом, заключена в ограниченном «бюджете внимания» моделей: если передать в промпт слишком много инструкций, агент начинает игнорировать часть из них, что исследователи называют «проклятием инструкций».
Чтобы минимизировать эту проблему, Османи рекомендует дробить задачу на отдельные модули, предоставляя агенту фокус на одну конкретную цель и подгружая только релевантный контекст. В результате уточняется структура спецификации, которая должна содержать шесть основных разделов: команды (с подробным описанием и флагами), процедуру тестирования, структуру проекта, стиль кода (лучше конкретный пример, чем развернутое описание), git-воркфлоу и чётко обозначенные границы действий агента. В последнем пункте разработчик предлагает разграничить действия на три категории: «всегда делать», «сначала спрашивать» и «никогда не делать» — наиболее частым ограничением оказалось запрет на коммит секретных данных.
Кроме того, Османи советует начинать с высокого уровня и предоставлять агенту возможность развернуть детальный план самостоятельно, начиная с режима только чтения без генерации кода. Спецификация в этом случае трансформируется в живой документ, который необходимо регулярно обновлять и считать главным источником правды для всех сессий взаимодействия с агентом. Для сложных проектов рекомендуется разделять обязанности между несколькими специализированными субагентами, например, отвечающими за базу данных, API и фронтенд.
Особое внимание в гайде уделено самопроверкам: в спецификацию важно встроить инструкции, по которым агент контролирует соответствие результатов ожиданиям. Для оценки субъективных параметров, таких как читаемость кода или архитектурные соответствия, Османи предлагает использовать подход LLM-as-a-Judge, когда второй AI-агент ревьюирует работу первого. Также в документ следует включать накопленную экспертизу — особенности работы с библиотеками, редкие кейсы и предпочтения по стилю кодирования, что невозможно передать машине без явных указаний.
Завершая обзор, автор подчёркивает важность итеративного подхода: спецификацию нужно тестировать как можно раньше, обновлять после каждого нового открытия и не откладывать совершенствование до финальной стадии проекта. В качестве метафоры Османи приводит слова Саймона Уиллисона, который сравнил взаимодействие с AI-агентами с управлением интерном, способным халтурить при отсутствии чёткого контроля. Спецификация, по мнению автора, служит именно таким инструментом — задаёт рамки, включает встроенные проверки и не даёт агенту отклониться от задачи.
