Главная / Статьи

Ваш файл AGENTS.md был создан для более слабой модели: аудит задолженности по промптам

Старые правила AGENTS.md остаются в силе даже после устранения ошибок модели, которые они исправляли. Научитесь распознавать проблемы с запросами, сокращайте наборы навыков до необходимого минимума, устанавливайте разрешения и определяйте критерии завершения работы заранее.

Издатель: REACTAPP.TOP8 мин чтения1854 слов

Источники: Your AGENTS.md Was Written for a Worse Model

Каждая строка в файле AGENTS.md обычно добавлялась для устранения реальной проблемы. Модели совершенствуются, проблема уменьшается, но правило остается. Это так называемый «долг по промптам»: временное решение проблемы одной модели превращается в постоянную политику. Решением является назначение файлу более узкой задачи — охвата инвариантов, скрытых ограничений и границ разрешений, а также определения критериев завершения работы.

Каждый раз, когда кодинг-агент допускает ошибку, которая запоминается людьми, кто-то добавляет новое правило. Оно вносит слишком много изменений, поэтому в файле указано, что следует менять только необходимое. Оно пропускает проверку, поэтому каждый раз требуется выполнение всего набора тестов. Оно без спроса меняет зависимости, из-за чего любые изменения зависимостей становятся возможными только с одобрения. Оно «блуждает» по репозиторию, поэтому в файле прописаны документы, которые следует прочитать в первую очередь.

Каждое правило казалось разумным в момент его создания. Затем изменилась модель.

OLD: Read A → Edit B → Test C
NEW: Boundaries → Permissions → Definition of done

Новое поколение моделей, примером которого служит GPT-6 Astra, значительно лучше выполняет инструкции по сравнению с более ранними моделями для кодирования, что меняет экономику формулировки запросов. Слабая модель может проигнорировать слишком общее правило, тогда как сильная может следовать ему буквально. Поэтому инструкция, написанная для устранения недостатков старой модели, может стать препятствием для новой. Если обновить модель, не проверив её инструкции, старые слабости останутся в качестве постоянной политики внутри новой системы. Модель улучшилась, но структура запросов осталась прежней.

Каждая неудача оставляет «фоссиля»

Код накапливает технический долг, когда временное решение на местном уровне превращается в структурное ограничение. Инструкции для агентов накапливают долг точно таким же образом.

Предположим, старая модель для кодирования постоянно забывала проверять свои изменения, поэтому кто-то добавил:

Always run the entire test suite after every change.

В то время это, возможно, улучшило надежность. Через год модель уже может выявлять поврежденные тесты и проверять свою работу, однако инструкция по-прежнему существует. Теперь одна-единственная правка может запустить двадцатиминутные тесты интеграции. Ничего не сломано, и агент верно следует правилам репозитория. Проблема в том, что старый патч поведения был превращен в постоянную инженерную политику.

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

Навыки стоят денег до того, как они начнут работать

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

Однако прежде чем модель сможет выбрать навык, ей необходимо распознать доступные варианты, поэтому названия и описания уже соперничают за внимание.

Представьте хранилище с отдельными навыками, охватывающими миграции баз данных, PostgreSQL, проектирование схем, сохранение данных на серверной части, оптимизацию запросов и восстановление. Каждый из них сопровождается общим описанием, в котором упоминаются SQL, миграции, схемы, запросы, модели и хранилище данных. Даже незначительная корректировка запроса теперь кажется релевантной для половины элементов библиотеки, поэтому агенту приходится сначала классифицировать информацию, прежде чем начать писать код.

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

database/
├── router.md
└── references/
    ├── migrations.md
    ├── performance.md
    └── recovery.md

Для выполнения задачи корневому файлу достаточно лишь минимальных данных. Изменение схемы приводит к файлу migrations.md, медленный запрос — к файлу performance.md, восстановление или потеря данных — к файлу recovery.md. Детали не удаляются; они появляются тогда, когда задача дает агенту причину их прочитать, что позволяет лучше использовать контекст, чем опираться на догадки при работе с операционными знаниями.

В файле AGENTS.md должно храниться то, что невозможно объяснить кодом

Инструкции на уровне репозитория ведут себя иначе, поскольку они сопровождают агента практически при каждой задаче. Файлы вроде AGENTS.md загружаются в сессию в качестве постоянного контекста, как описано в документациях по памяти Claude Code, и поэтому их использование становится неэффективным, если они неверны, устарели или слишком общие.

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

Сравните два указания. Первое представляет собой знания, специфичные для репозитория, которые модель не может безопасно вывести, поэтому оно остаётся:

KEEP
Generated API clients in /src/sdk are immutable.
Edit the generator source instead.

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

MOVE OR REMOVE
Before making any change:
1. Read ARCHITECTURE.md
2. Inspect the repository map
3. Review all package documentation
4. Identify downstream dependencies

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

Лучшие модели делают разрешения более важными

Более строгое следование инструкциям приводит к более тонкой проблеме: агент может настолько тщательно соблюдать установленные границы, что останавливается именно там, где вы хотели, чтобы он продолжил действовать.

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

Local tests use disposable fixtures and have no production access.
Run affected tests, fix regressions caused by the requested change,
and rerun them without asking for approval at each step.

Эти строки сообщают агенту три вещи, которые он не всегда может определить самостоятельно: среда безопасна, действия по устранению проблем входят в рамки задачи, и он может продолжать работу. Таким образом установленные границы лучше направляют принятие решений, чем абсолютные запреты вроде «никогда не расширять объем задачи».

Один из способов разделения ответственности на практике:

Требует одобрения человека:

  • Удаление производственных данных.
  • Изменение политики аутентификации.
  • Нарушение условий публичного API.
  • Внедрение миграции с операционными рисками.

Агент обычно может продолжить выполнение следующих действий:

  • Исправление теста, который был поврежден его собственными изменениями.
  • Обновление смежных локальных типов.
  • Форматирование файлов, которые он изменял.
  • Повторная запуск поврежденных локальных тестов.

Разница между этими действиями определяет необходимость уровня одобрения. Соседние действия не всегда требуют одинакового уровня одобрения.

Определите критерии завершения работы перед описанием процедуры

В более старых запросах часто описывается маршрут:

Read these files.
Modify these modules.
Run this command.
Inspect this output.
Run these tests.

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

Implement the avatar endpoint.

версия с финишной линией:

Run the affected local tests, inspect the returned payload,
fix regressions caused by this change, and stop when the requested
behavior works or an external blocker requires a decision from me.

Второй компонент не указывает, какой файл следует открыть в первую очередь. Он описывает, как будет выглядеть готовый результат. Это различие становится всё более значимым по мере того, как модели приобретают достаточную способность к принятию решений для выбора собственного пути внутри кодовой базы. Люди задают конечную точку и опасные участки, а агент определяет маршрут.

Следите за целенаправленностью иерархии инструкций

Чёткая структура включает три отдельных уровня. Первым является файл репозитория:

AGENTS.md
    ↓
Repository invariants
Safety boundaries
Global permissions

Второй вариант включает в себя навыки:

Skills
    ↓
Specialized workflows
Loaded only when relevantTask prompt
    ↓
Immediate objective
Local constraints
Definition of done

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

Проверка на наличие избыточных инструкций при изменении модели

Обновление модели должно стимулировать проверку существующих инструкций. Это не потому, что все старые инструкции неверны, а потому, что предпосылки, лежащие в их основе, могли измениться. Эффективная проверка включает четыре этапа.

Подведение итогов по историческим инструкциям

Соберите всё, что влияет на поведение агента:

  • AGENTS.md
  • описания навыков
  • сами навыки
  • инструкции на уровне системы из репозитория
  • Инструкции, повторяющиеся в шаблонах задач

Для каждого правила выясните, почему оно существует и какая проблема первой побудила к его добавлению.

Различайте истинные неизменные факторы и привычки

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

Преобразуйте сложные навыки в универсальные инструменты

Если один навык используется в нескольких рабочих процессах, сократите точку его применения. Загружайте инструкции по миграции только при необходимости миграции, а инструкции по восстановлению — только тогда, когда это актуально. Специализированные знания останутся, не будучи включенными в каждую близлежащую задачу.

Перечитайте каждое запретительное правило, чтобы понять скрытый риск

Правила вроде «НИКОГДА не трогай X», «ВСЕГДА спрашивай перед Y» или «ИЗМЕНЯЙ ТОЛЬКО Z» могут оставаться правильными, но каждое из них следует проверять с учётом последствий, которые оно предназначено предотвратить. Иногда лучшим правилом будет то, что X можно свободно изменять во время локальной разработки, но перед этим необходимо задать вопрос в производственной среде, или что регрессии, возникшие из-за собственных изменений агента, можно исправить, тогда как более масштабные изменения требуют одобрения.

Цель не в максимальной автономии. Она заключается в том, чтобы направлять внимание людей туда, где последствия этого оправданы.

Что должно сохраняться после каждого обновления

Некоторые инструкции остаются важными, независимо от качества моделей. Для развертывания может потребоваться недокументированный флаг наследия. Сгенерированные файлы могут казаться редактируемыми, хотя любые изменения сразу стираются. Локальная среда может имитировать производственную при использовании временных элементов. Миграция может потребоваться для работы с двумя действующими версиями приложения. Эти аспекты имеют высокую ценность, поскольку одних только алгоритмов недостаточно для их обнаружения.

Фильтром для выбора должна служить ценность информации. Если инструкция содержит что-то, что модель не может безопасно выявить, её следует сохранить. Если же она лишь описывает, как старая модель должна была выполнять обычную инженерную задачу, её стоит пересмотреть. Количество инструкций само по себе не создаёт проблему «долга по промптам»; проблема заключается в тех инструкциях, причина существования которых исчезла.

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