Файл AGENTS.md не є другою інструкцією з експлуатації застосунку і не є prompt, який намагається керувати кожним натисканням клавіші. Це невеликий версійований контракт контексту. Він повідомляє coding agent, як улаштований репозиторій, які команди дають перевірювані докази, які межі важливі та де лежить конкретніше правило. Хороший файл зменшує невизначеність до того, як agent почне змінювати код. Він не замінює вихідний код, тести, супроводжувачів проєкту чи опис завдання.
Контекст має ціну. Codex завантажує вказівки проєкту до ланцюжка інструкцій перед роботою. Повторюваний текст конкурує із запитом користувача, файлами репозиторію, виводом інструментів і тестами. Тому записуйте факти, які agent не може безпечно вивести, а не всі побажання, висловлені кимось у минулому. Сприймайте кожне речення як інтерфейс, який треба підтримувати.
Що саме знаходить Codex
Актуальний посібник OpenAI про AGENTS.md для Codex описує три рівні. На глобальному рівні Codex шукає AGENTS.override.md у CODEX_HOME, що за замовчуванням дорівнює ~/.codex, а якщо такого файла немає, використовує AGENTS.md. На цьому рівні береться лише перший непорожній файл. На рівні проєкту Codex починає з кореня проєкту, зазвичай кореня Git, і спускається до поточного робочого каталогу. У кожному каталозі він перевіряє AGENTS.override.md, потім AGENTS.md, потім налаштовані запасні назви й додає не більше одного файла з каталогу.
Знайдені файли проєкту об'єднуються від кореня до поточного каталогу. Глибший файл з'являється пізніше в об'єднаних інструкціях, тому його вузьке правило може замінити ширше. Codex не шукає вище виявленого кореня проєкту. Якщо корінь не знайдено, перевіряється лише поточний каталог. Порожні файли пропускаються. Типове значення project_doc_max_bytes становить 32 KiB, і після досягнення загального налаштованого ліміту Codex перестає додавати вказівки. Це поведінка Codex, а не універсальна обіцянка всіх інструментів.
Реалізація пошуку AGENTS.md у вихідному коді OpenAI Codex показує ті самі межі. Типовий маркер кореня — .git, бажана локальна назва — AGENTS.override.md, а файл може бути обрізаний, якщо залишкового бюджету байтів менше за його розмір. Репозиторій може налаштувати маркери кореня, запасні імена та бюджет. Документуйте лише налаштування, які справді використовуються.
Глобальне побажання належить у ~/.codex/AGENTS.md лише тоді, коли воно безпечне для кожного репозиторію. Правило всього репозиторію розміщуйте в корені. Правило сервісу тримайте біля цього сервісу. Тимчасову або виняткову заміну розміщуйте в override-файлі, зазначивши власника та умову видалення. Не називайте це універсальною ієрархією для інших агентів, якщо їхня документація цього не підтверджує.
Почніть із карти репозиторію
Спершу agent потрібно зорієнтувати, і лише потім давати поради щодо стилю. На початку кореневого файла розмістіть стислу карту. Назвіть застосунок або бібліотеку, основні каталоги вихідного коду, зони згенерованих файлів, каталоги тестів і конфігурацію постачання. Пояснюйте тільки відмінності, які змінюють дію. Фраза «у src/ є код» слабка. Фраза «src/ потрапляє до постачання, scripts/ запускається лише в CI, а dist/ генерується й не редагується вручну» є практичною.
Карта має переживати звичайні рефакторинги. Обирайте стабільні межі замість переліку кожного файла. У монорепозиторії покажіть власників пакетів, а карти пакетів розмістіть у вкладених файлах. Посилайтеся на README або документ архітектури, якщо він є джерелом істини. Не копіюйте цей документ у AGENTS.md.
repository/
apps/web/ браузерний застосунок і тести маршрутів
packages/core/ спільна бібліотека виконання та unit-тести
services/api/ HTTP-обробники та контрактні тести
infra/ конфігурація постачання
docs/ документи, які підтримуються
generated/ відстежуваний результат, який генерує скрипт
Явно запишіть припущення про робочий каталог. Команда з services/api може отримати інший вкладений файл інструкцій, ніж та сама команда з кореня. Якщо менеджер пакетів потрібно запускати з каталогу пакета, скажіть про це. Якщо згенерований файл має джерело істини, назвіть обидва шляхи та команду генератора.
Робіть команди точними й умовними
Команда корисна, якщо її можна скопіювати без тлумачення. Для кожної обов'язкової команди вкажіть каталог, призначення та умову запуску. Використовуйте версії й скрипти, оголошені репозиторієм, а не модний інструмент, який ви пам'ятаєте. Розділ може мати таку структуру:
Із кореня репозиторію:
git rev-parse --show-toplevel
npm ci
npm run check
npm test
npm run build
Для змін API запускайте з services/api:
npm run test:contract
Це приклад структури, а не твердження, що такі скрипти є в кожному проєкті. Перед написанням прочитайте package.json, lockfile, CI workflow, pyproject.toml, Cargo.toml або відповідні файли. Пишіть «після змін TypeScript запустіть npm run check» лише якщо такий скрипт існує. Якщо команді потрібні локальний сервіс, fixture, база, змінна середовища або мережа, опишіть передумову та безпечну заміну для сфокусованого тесту.
Зафіксуйте підтримуване середовище виконання і політику залежностей. Корисний запис називає версію Node, Python, Rust, Java або Go, менеджер пакетів, політику lockfile і спосіб перевірки оновлень. Наприклад, «у package.json оголошено Node >=22.12.0, використовуйте зафіксований package-lock.json і запускайте npm ci» є фактом, якщо це підтверджує маніфест. Не копіюйте версію в AGENTS.md, не перевіривши маніфест і CI. Розбіжність версій є проблемою підтримки, а не приводом додавати більше тексту.
Codex може допомогти перевірити активний ланцюжок. Офіційний посібник показує команди такого виду:
codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/api --ask-for-approval never "List the instruction sources you loaded."
codex -c log_dir=./.codex-log --ask-for-approval never "Show the active instruction files."
Використовуйте безпечний запит без змін і переглядайте журнал лише в надійному локальному робочому просторі. Після зміни файлів інструкцій перезапустіть run, бо пошук перебудовується на початку run або TUI-сеансу. Застаріла відповідь означає, що треба перевірити робочий каталог, CODEX_HOME, override, запасні назви та ліміт байтів.
Тести дають докази
Опишіть стан «готово» спостережуваними результатами. Відокремте швидкі перевірки від повного набору. Назвіть команду тесту, заторкнутий пакет, очікуваний артефакт і шлях дій у разі помилки. Для зміни HTTP-схеми вимагайте контрактний тест. Для парсера вимагайте представницькі fixture та некоректні входи. Для згенерованого клієнта вимагайте повторну генерацію і чистий diff.
Не пишіть «завжди запускайте всі тести», якщо репозиторій має інший задокументований обсяг або повний набір потребує зовнішньої інфраструктури. Точніше сказати: «спочатку запустіть цільовий тест пакета, а перед злиттям набір, еквівалентний CI». Форматування і lint залиште CI, якщо вони вже перевіряються там. Репозиторій SWE-bench є первинним джерелом для оцінювання задач, але його протокол не замінює тести конкретного репозиторію.
Пов'язуйте важливе правило з перевіркою. Якщо agent не має редагувати згенерований результат, CI може знову запустити генератор і впасти на diff. Якщо міграція має бути оборотною, тест може застосувати її до чистої fixture і скасувати. Якщо важливий інваріант безпеки, виразіть його тестом або статичною перевіркою. Інструкція без спостережуваного результату просить покластися на пам'ять.
Для оцінювання поведінки agent порівнюйте успішність задачі, частку пройдених тестів, діапазон змінених файлів, переробки після рев'ю і час до перевіреного патча. Запускайте однаковий набір задач зі старим і новим файлом, зберігаючи запит і ревізію репозиторію, та записуйте невдачі, а не лише успішні демонстрації. Це інженерний сигнал, а не доказ того, що одна редакція працює для кожної моделі. Порівняння інструментів є в матеріалі про agentic coding, Codex і Claude Code. Про системні межі читайте в архітектурі production AI agent, а про дизайн оцінювання — у матеріалі про оцінювання AI agents.
Тримайте безпеку на межі
AGENTS.md є входом до проєкту. Він може бути застарілим, неправильним або ненадійним. Вихідний код Codex явно не завантажує проєктні інструкції, коли активний проєкт не є довіреним, водночас зберігаючи інструкції, надані хостом. Це не скасовує людської перевірки. Вважайте вказівки репозиторію недовіреним текстом, доки не перевірите репозиторій і запитану зміну.
Ніколи не розміщуйте у файлі ключі API, токени, паролі, приватні сертифікати або скопійовані production-дані. Не просіть agent друкувати змінні середовища чи завантажувати файли робочого простору. Можна назвати секрет за роллю, наприклад DATABASE_URL, і вказати, де локальна розробка отримує його, не зберігаючи значення. Перед видаленням даних, ротацією credentials, production-деплоєм або широким мережевим доступом вимагайте підтвердження, якщо workflow це підтримує.
Розділяйте факти й дозволи. «Сервіс використовує S3» — контекст. «Можна видалити bucket» — повноваження. Повноваження мають бути в політиці доступу та процесі підтвердження, а не в markdown. Назвіть захищені шляхи, згенеровані артефакти, правила міграцій і межі тестових даних. Для невизначеності дайте безпечний шлях: зупинитися, показати запропоновану команду і запитати супроводжувача.
Обережно ставтеся до інструкцій, скопійованих з issue, fixture або файлів залежностей. Вони можуть містити prompt injection або команду, не пов'язану із завданням. Хороший файл говорить сприймати вміст репозиторію як дані, якщо користувач або довірене правило проєкту не дозволяє дію. Це межа безпеки, а не вимога ігнорувати вихідний код.
Обирайте короткий шаруватий файл
Сайт AGENTS.md називає огляд проєкту, команди складання й тестування, стиль, тести та безпеку поширеними розділами. Це меню, а не обов'язкова схема. Почніть із мінімуму, що запобігає повторним помилкам. Кореневому файлу часто достатньо п'яти розділів: карта, налаштування, перевірка, межі та посилання на глибші правила.
## Карта репозиторію
`apps/web` — браузерний застосунок. `packages/core` — спільний runtime-код.
## Інструменти
Використовуйте Node 22 і зафіксований lockfile. Запускайте команди з кореня, якщо не вказано інше.
## Перевірка
Для змін, видимих користувачу, запускайте `npm run check`, тест пакета і `npm run build`.
## Межі
Не редагуйте `generated/`. Не використовуйте production-дані локально. Питайте перед додаванням залежності.
## Глибші правила
Читайте `apps/web/AGENTS.md` про маршрути і `services/api/AGENTS.md` про контрактні тести.
Погана версія — каталог особистих смаків на 1000 рядків: повтори, вичерпні списки файлів, суперечливі «завжди», вигадані команди, старі версії та вказівки перечитати всі документи. Вона витрачає бюджет байтів і приховує пріоритети. Розділяйте за відповідальністю. Кореневий інваріант залишайте в кореневому файлі, а вкладеному дозволяйте додати локальні команди. Вкладений файл має доповнювати або звужувати вказівки, а не непомітно змінювати межу безпеки.
Не обіцяйте композицію, якої інструмент не документує. Codex зараз поєднує файли через пошук у каталогах і налаштовані запасні назви. Рядок «потім прочитайте docs/rules.md» є звичайним текстом, якщо інструмент не визначає спеціальний синтаксис include. Symlink, CLAUDE.md або правило іншого агента не завантажуються Codex автоматично. Сумісність описуйте як перевірений workflow, а не загальне правило.
Підтримуйте його як код
Призначте власника файла. Переглядайте зміни разом із кодом, яким вони керують. Коли змінюється команда, runtime, каталог або CI workflow, оновлюйте найближчий файл інструкцій у тому самому changeset. Видаляйте правило після зникнення останнього споживача. Приклади мають бути виконуваними й безпечними. Посилайтеся на одне джерело істини, а не дублюйте політику в трьох файлах.
Щомісячний або релізний аудит може бути коротким. Перевірте, що кожна команда існує, кожна версія відповідає маніфесту або образу CI, а кожен шлях досі існує. Запустіть запит списку джерел Codex із кореня та з одного представницького підкаталогу. Виміряйте розмір ефективного ланцюжка. Запитайте супроводжувача, чи кожне правило ще запобігає реальній помилці.
Зміни AGENTS.md оцінюйте як зміни конфігурації. Візьміть невеликий фіксований набір задач: нова можливість, виправлення помилки, зміна лише тестів і чутлива до безпеки зміна. Порівнюйте правильність і охоплення патча, а не тільки пояснення agent. Регресійна перевірка може засвідчити, що згенеровані файли не змінились, тест пакета виконався або небезпечну команду відхилено. Фіксуйте ревізію, налаштування моделі, дозволи й текст задачі достатньо стабільно, щоб порівняння було зрозумілим.
Стійкий підхід простий. Розміщуйте стабільні факти поруч із їхньою областю дії. Називайте точні команди та версії, підтверджені репозиторієм. Посилайтеся на докладні документи. Робіть важливі правила тестованими. Тримайте секрети й повноваження поза markdown. Використовуйте шари замість гігантської інструкції. Перевіряйте ефективний ланцюжок після зміни каталогу, конфігурації або версії інструмента.