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

Создание и структура файла AGENTS.md для управления контекстом проекта

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

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

Структура файла должна быть лаконичной. Избегайте общих фраз вроде «пиши качественно» или «будь внимателен». Вместо этого используйте конкретные правила: например, «не удалять существующие компоненты без явного указания» или «использовать библиотеку X для обработки данных».

Разделяйте типы документов. README предназначен для людей и описывает проект на понятном языке. AGENTS.md задает рабочие правила для агента. Техническое задание (ТЗ) описывает конкретную функциональность, которую нужно реализовать в данный момент. Эти документы могут ссылаться друг на друга, но не должны дублировать содержимое.

Методика формулирования задач с чёткими границами изменений

Проблема неконтролируемых изменений возникает, когда запрос не содержит четких границ. Например, просьба «сделай нормально» или «приведи в порядок» допускает разные трактовки: для владельца это может быть исправление отступа, а для исполнителя — полная переработка компонента.

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

Пример правильной формулировки: «После успешной отправки формы покажи сообщение “Заявка отправлена”. Повторное нажатие во время отправки не должно создавать вторую заявку. Остальной сценарий сохрани».

Если задача временная, например добавление фильтра по статусу, описывайте её непосредственно в сообщении, а не записывайте как постоянное правило в AGENTS.md. Глобальные файлы должны содержать только фундаментальные ограничения проекта.

Иерархия приоритетов при наличии нескольких файлов инструкций

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

В одной директории файл AGENTS.override.md имеет приоритет над основным файлом AGENTS.md. Это позволяет локально переопределять глобальные настройки без изменения основного файла.

Не создавайте файлы override без необходимости. Используйте их только для специфических требований к определенным модулям или этапам разработки. Если в корневом файле указано «не менять структуру базы данных», а в локальном override прописано исключение для конкретного скрипта, ИИ выполнит именно локальное правило.

Убедитесь, что файлы не противоречат друг другу. Конфликт возникает, если в одном месте сказано «использовать React», а в другом — «использовать Vue». В таком случае поведение агента становится непредсказуемым.

Процедура проверки результатов работы ИИ перед принятием

Фраза «готово» сама по себе не доказывает, что приложение соответствует задаче. Вам необходимо самостоятельно определить критерии успеха и проверить их.

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

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

Для сложных проектов используйте автоматические проверки. Настройте скрипты, которые проверяют наличие зависимостей и целостность кода после каждого запуска агента.

Вопросы и ответы

Можно ли хранить в AGENTS.md логику бизнес-процессов?

Нет. В AGENTS.md храните только технические ограничения и правила работы с кодом. Бизнес-логику описывайте в техническом задании или в отдельных файлах проекта.

Что делать, если ИИ игнорирует файл override?

Убедитесь, что файл находится в той же директории, что и AGENTS.md. Если он лежит глубже в структуре папок, проверьте, не перекрывает ли его другой локальный файл с более высоким приоритетом.

Как избежать случайных изменений при обновлении зависимостей?

В AGENTS.md явно укажите список разрешенных пакетов и запретите установку новых версий без вашего подтверждения. Добавьте правило: «Не обновлять зависимости автоматически».

По теме

Похожие статьи