Codex Guide

Тема

Контекст, AGENTS.md и инструкции ​

Проверено: 20 июля 2026 года.

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

Что хранить в AGENTS.md ​

Хороший проектный файл кратко фиксирует:

  • карту репозитория и границы модулей;
  • реальные команды установки, тестов, lint, сборки и smoke-check;
  • локальные архитектурные соглашения, которые не очевидны из кода;
  • ограничения безопасности, данных и production;
  • критерии готовности и обязательный формат проверки;
  • ссылки на подробные документы вместо их копирования.

Вложенный AGENTS.md нужен, когда каталог действительно имеет другой стек, команды или правила. Ближайшая инструкция имеет приоритет для своего дерева.

Что не хранить в AGENTS.md ​

  • общеизвестные советы без локальной ценности;
  • длинные туториалы и справочники API;
  • полный список правил formatter/linter;
  • пошаговый workflow, который лучше оформить skill;
  • секреты, токены, содержимое .env и приватные данные;
  • изменчивые факты без даты и первоисточника;
  • команды, способные менять production, как повседневный путь проверки.

Официальный механизм обнаружения имеет ограниченный суммарный объём инструкций (по умолчанию 32 KiB), а инструкции читаются заново при старте сессии. После изменения AGENTS.md полезно начать новую сессию и попросить Codex перечислить активные инструкции. См. официальное руководство AGENTS.md.

Прогрессивное раскрытие ​

text
AGENTS.md: карта, обязательные команды, запреты, ссылки
    ├── docs/: подробная архитектура и стандарты
    ├── skill: повторяемая процедура с ресурсами и скриптами
    ├── config/rules/hooks: разрешения и механическое исполнение
    └── MCP: актуальные внешние данные и действия

В AGENTS.md следует ссылаться на документы, которые Codex должен читать только при соответствующем типе задачи. Этот справочник устроен так же.

Типичные запахи конфигурации ​

  • Context bloat: большой текст скрывает важные ограничения.
  • Lint leakage: в инструкции вручную переписаны правила инструмента.
  • Skill leakage: сложная повторяемая процедура встроена в каждый промпт.
  • Дублирование: одно правило расходится между несколькими файлами.
  • Конфликт области: корневое правило не подходит вложенному модулю.
  • Непроверяемость: требование нельзя подтвердить тестом или наблюдением.

Эти риски подтверждаются исследованием 100 open-source-репозиториев (Configuration Smells in AGENTS.md).

Как улучшать инструкции ​

  1. Зафиксировать конкретную повторившуюся ошибку.
  2. Определить минимальное новое правило или ссылку, предотвращающую её.
  3. Разместить правило в самой узкой области действия.
  4. Удалить дублирование и устаревшие формулировки.
  5. Проверить на реальной задаче стоимость контекста и результат.

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