Файлы инструкций для агентов программирования с искусственным интеллектом нуждаются в постоянном пересмотре, а не в бесконечном расширении. После каждой ошибки модели добавляется новое правило, при каждом изменении инструмента — обходной способ, а прежние рекомендации для моделей сохраняются после появления более новых моделей. В результате файл может превратиться в сочетание руководства по настройке для разработчиков, руководства по стилю, журнала устранения неполадок и набора устаревших методов формулирования запросов.
Согласно статье, такое накопление может снизить эффективность агента программирования. Современные модели лучше умеют исследовать репозитории, распознавать распространённые фреймворки, следовать существующим шаблонам и обрабатывать обычные ошибки. Однако им неизвестны командные решения, скрытые ограничения и накопленный внутри команды операционный опыт. Поэтому цель состоит не в том, чтобы сделать файл инструкций как можно короче, а в том, чтобы сохранить минимальный набор информации с высокой сигнальной ценностью, которая действительно меняет результат.
Рассматривайте контекст как ограниченный ресурс
Файл инструкций добавляется к доступному модели контексту в каждом подходящем запросе, и его строки конкурируют за внимание модели с задачей разработчика, связным кодом, выводом инструментов, историей диалога и другими инструкциями. Большое окно контекста не означает, что каждый дополнительный символ ничего не стоит.
Практический вопрос заключается не в том, что можно рассказать модели о репозитории, а в том, что модели необходимо знать и что она не может надёжно обнаружить, вывести или извлечь. Статья рекомендует сосредоточиться на конкретной, значимой и трудно выводимой информации.
Что следует оставить в файле?
Наиболее ценная информация включает неочевидные факты о системе, например границы владения между компонентами репозитория, то, что старый каталог всё ещё используется в production, или то, что определённые файлы генерируются и их нельзя изменять вручную. Полезно уточнить, что определённый интерфейс владеет публичным HTTP-контрактом или что правила предметной области относятся к конкретному слою, вместо того чтобы оставлять модели возможность выводить эти границы по именам каталогов.
Также следует задокументировать кратчайший надёжный путь сборки и проверки, ограничившись проверенными командами. Среди приведённых в статье примеров — запуск dotnet restore App.slnx перед первой сборкой, затем использование dotnet build App.slnx --no-restore, запуск конкретных тестов при изменении API или инструмента проверки сгенерированных файлов после изменения контрактов. Необходимо уточнять особые требования, например необходимость Docker для интеграционных тестов и запрет на их параллельный запуск, поскольку неверная команда, которую уверенно повторяют, хуже отсутствия команды.
Полезно также фиксировать локальные решения, которые код не может постоянно определять самостоятельно: используемый фреймворк тестирования, предпочтение Minimal APIs контроллерам, шаблон Result<T> для обработки ожидаемых ошибок предметной области или использование TimeProvider вместо прямого обращения к системным часам. Это не общие правила программирования, а решения, специфичные для конкретной кодовой базы, поэтому им место в файле инструкций.
Что касается строгих ограничений, слова «всегда», «никогда» и «должен» следует резервировать для действительно абсолютных правил, таких как сохранение публичного JSON-контракта, запрет на размещение клиентских данных в журналах, совместимость миграций базы данных с предыдущей версией или запрет на изменение файлов production-окружения без явно указанной задачи развёртывания. Также можно ссылаться на источники истины, а не копировать их содержимое: файлы с рекомендациями по дизайну интерфейсов, файлы фиксации версий среды выполнения, документацию по развёртыванию и архитектурные решения.
Что можно удалить или перенести?
Статья советует удалять общие рекомендации вроде написания чистого кода, следования лучшим практикам, использования осмысленных имён и корректной обработки ошибок. Такие формулировки не определяют практическое решение, тогда как конкретное локальное правило приносит больше пользы: например, связывать ошибки валидации с ответом 400, отсутствующие ресурсы — с ответом 404, а конфликты параллелизма — с ответом 409, используя имеющиеся инструменты ProblemDetails.
Обычно файлам не нужен полный перечень каталогов, поскольку модель может быстро прочитать структуру репозитория. Не нужно и повторять правила форматирования, которые обеспечиваются инструментами; достаточно указать подходящую команду проверки, например dotnet format --verify-no-changes. Следует избегать полного копирования README, архитектурных руководств и руководств по внесению изменений, чтобы не увеличивать стоимость сопровождения и не создавать противоречия между документами.
Статья также предостерегает от старых «мифов о запросах», например предложений модели сделать глубокий вдох, вести себя как старший инженер или прочитать каждый файл перед любым изменением. Эти фразы не добавляют знаний о проекте и могут привести к ненужному исследованию. Лучше описывать результат, ограничения и необходимую проверку: внести минимальное изменение, устраняющее первопричину, сохранить общее поведение и запустить целевые тесты.
Временные решения следует удалять после устранения вызвавшей их проблемы. Иначе агент продолжит избегать пути, который больше не является неисправным. Инструкции также следует писать для класса моделей, а не для конкретной версии; инструкции, разветвляющиеся на отдельные пути для каждой модели, становятся хрупкими по мере изменения моделей и их поведения.
Выбор области действия и пересмотр инструкций
Не каждое указание подходит для общего файла репозитория. GitHub Copilot поддерживает общие инструкции в .github/copilot-instructions.md, файлы для отдельных путей в .github/instructions/ и инструкции для агентов, такие как AGENTS.md. При наличии обоих файлов общий файл инструкций используется вместе с файлом для соответствующего пути.
Архитектуру системы, общие команды и общие ограничения следует размещать в общей области, а правила фреймворков, шаблоны тестирования и сгенерированные файлы, относящиеся к отдельной части, переносить в файл для соответствующего пути. Подробные объяснения, историю решений и редкие процедуры лучше хранить в связанных документах. Благодаря этому правило для тестов компонентов React не будет занимать внимание модели во время задачи по миграции базы данных.
Статья предлагает оценивать каждое указание по четырём результатам: оставить, если оно верно, значимо и трудно выводимо; удалить, если модель его знает, оно обеспечивается инструментом либо стало неоднозначным или устарело; перенести, если оно полезно, но относится к другому пути или документу; и проверить, если оно касается команды, временного решения или версии, которая могла измениться.
Поводами для пересмотра могут быть внедрение более способной модели, изменение системы сборки, реорганизация репозитория или наблюдение за тем, что агенты игнорируют инструкции либо применяют их неправильно. После этого меньший файл проверяют на конкретной задаче, отслеживают фактические случаи сбоев, добавляют минимальный набор инструкций, предотвращающий их повторение, и повторно тестируют файл на другой задаче.
Часть сопровождения проекта
Статья призывает пересматривать изменения файлов инструкций в рамках обычных pull request, спрашивать у рецензентов, пригодно ли правило для повторного использования или оно относится только к одной задаче, а также назначать владельца операционных команд и требований к окружению. Временные решения следует удалять в том же pull request, который устраняет первопричину проблемы, а команды нужно повторно проверять после обновлений пакетов SDK, фреймворков, инструментов тестирования или конвейера сборки.
Не следует оценивать качество файла по количеству строк. Файл из 30 строк, содержащий ошибочные указания, может быть хуже файла из 100 строк, в котором описаны границы многопроектного репозитория и сведения, которые модель не может вывести самостоятельно. Лучший критерий заключается в том, позволяет ли файл способной модели быстро приступить к работе, предоставляя ей сведения, известные только команде: что представляет собой система, каковы важные границы, какие решения приняты локально, как выполнять сборку и проверку, что нельзя нарушать и где найти более подробные сведения.