Ваши инструкции агенту вредят: OpenAI объясняет, что удалить прямо сейчас

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

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

• Плохо: «Создание и проверка миграций схемы Postgres. Использовать при работе с базами, запросами, моделями или хранением».
• Хорошо: «Создание и проверка миграций схемы Postgres. Использовать при добавлении или изменении миграции либо при разборе её выката».

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

Третье наблюдение неприятно тем, кто вложился в подробные инструкции: многие скиллы написаны как детальные маршрутные листы. Модели стали заметно лучше понимать нюансы и неоднозначность, поэтому избыточная конкретика теперь мешает там, где раньше помогала.

Есть и то, о чём легко забыть: скиллы в репозитории направляют агентов других участников команды, а у них могут быть другие модели. Указание, которое помогает одной модели, способно переограничить GPT-6 Astra.

Файл AGENTS.md действует всякий раз, когда модель работает в репозитории, поэтому его содержимое нужно регулярно пересматривать: каждое правило ещё нужно?

Требование прочитать стопку документов перед любой правкой избыточно, если чинится опечатка. Astra способна сама понять, что ей нужно прочитать. Вместо «перед каждой правкой читай architecture.md, database.md и deployment.md» полезнее контекстный указатель: architecture.md — про границы сервисов, database.md — про изменения схемы, deployment.md — когда готовится выкат.

Прошлые модели приходилось подталкивать к запуску тестов и самопроверке. Astra делает это сама, и старые инструкции приводят к лишним прогонам.

Отдельная просьба — аккуратнее с формулировками границ. Если прошлая модель делала что-то без спроса и вы добавили жёсткое «сначала спроси», это может сработать против вас: Astra воспринимает такие указания серьёзно и останавливается там, где вы были бы рады продолжению.

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

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

Смена модели — хороший повод для уборки, и разбирать всё вручную не обязательно.

• Сократите описания скиллов до одной фразы «что делает» и одной «когда применять».
• Разнесите многосценарные скиллы: корневой файл-маршрутизатор плюс отдельные документы.
• Пройдите по AGENTS.md и вычеркните правила, которые были написаны под слабую модель: обязательное чтение всего подряд, напоминания про тесты, перестраховочные запреты.
• Проверьте, какие модели читают ваш репозиторий: инструкции пишутся не под одну.
• Опишите, что считается готовой задачей, и явно разрешите безопасные шаги.

Правило простое: инструкции — это тоже код, который устаревает. Каждая новая модель делает часть подпорок лишней, а лишняя подпорка не нейтральна, она отнимает контекст и уводит агента в сторону. Раз в релиз стоит перечитывать то, что вы написали агенту год назад.