AGENTS.md: інструкція, яку агент Codex справді читає перед роботою

Ви пояснюєте Codex те саме в кожній сесії: якою командою ганяти тести, куди не лізти, у якому стилі писати код. А через задачу агент знову запускає не той тест і лізе в папку, яку чіпати не можна. Розв’язок — не пояснювати щоразу довше в чаті, а один раз покласти правила у файл, який агент читає сам, ще до того, як напише перший рядок. Цей файл називається AGENTS.md.

Коротко (TL;DR)

AGENTS.md — це текстовий файл у корені репозиторію (або в підпапці), куди ви записуєте правила проєкту для агента: команди збірки й тестів, стиль коду, заборонені зони, очікування до pull request. Codex знаходить і читає його автоматично на старті задачі та враховує як контекст — наче нотатку від тімліда новому розробнику.

Що треба знати одразу:

• Файл знаходиться сам. Codex іде від кореня проєкту вниз до поточної папки й збирає всі AGENTS.md по шляху; окремо читає глобальний ~/.codex/AGENTS.md.
• Найближчий до задачі файл головніший. Правило в apps/web/AGENTS.md перекриває правило з кореневого AGENTS.md.
• Є ліміт. Codex складає файли, доки сумарний розмір не впреться в project_doc_max_bytes — за замовчуванням 32 KiB; далі додавати перестає.
• Створюється командою. У Codex CLI є команда /init — вона генерує стартовий AGENTS.md під ваш репозиторій.
• Це відкритий формат. Той самий файл читають Cursor, GitHub Copilot, Gemini CLI, Devin і ще два десятки агентів — ви пишете інструкцію один раз на всі інструменти.

Далі — як саме працює ієрархія, що писати всередину, готовий шаблон і де все це ламається.

BINANCE SIMPLE EARNЗмусь крипту працюватиВідсотки на USDT і BTC без блокування — гроші лишаються під рукою.Розмістити

Що таке AGENTS.md

AGENTS.md — це файл інструкцій проєкту для кодинг-агента: в офіційній документації OpenAI його називають «README для агентів». Різниця зі звичайним README проста. README пишуть для людини — як запустити проєкт, що він робить. AGENTS.md пишуть для агента — детальний контекст, який людині в README не потрібен, але без якого агент діє навмання: точні команди, межі, домовленості щодо коду.

Codex для не-програміста: як зібрати перший робочий продукт

Один продукт на Codex: як довести ідею до живого URL, не потонувши в коді

AMD Instinct Coder: стійка на вісьмох MI325X обіцяє мінус 70% до ціни токенів

Codex під контролем: як пісочниця і схвалення вирішують, що агенту можна

Codex — не чат-бот, а агент: як формулювати завдання, щоб він робив їх правильно

Агент читає цей файл на старті й тримає його в контексті всю сесію. Тому в нього кладуть те, що ви інакше повторювали б вручну щоразу: «тести ганяй через just test, а не cargo test», «у папку legacy/ не заходь», «перед PR прожени лінтер». Codex не додумує ці правила — він бере їх із файлу.

Ключова думка: AGENTS.md не робить агента «розумнішим», він робить його передбачуваним. Одна й та сама задача з добрим AGENTS.md і без нього дає різний результат — не тому, що модель інша, а тому, що в другому випадку агент не знає ваших домовленостей.

Якщо ви вже працювали з Claude Code, аналогія пряма: там ту саму роль грає файл CLAUDE.md. Ідея одна — винести правила проєкту у файл, який агент читає сам; про сам підхід керування агентом через такий файл ми докладно розбирали в матеріалі про метод роботи з кодинг-агентом. Тут фокус на Codex-специфіці: як саме OpenAI Codex знаходить, зливає й обмежує ці файли.

Як Codex знаходить і читає AGENTS.md

Це головне джерело плутанини, тому розберемо ієрархію AGENTS.md по кроках. Коли Codex стартує задачу, він збирає не один файл, а єдиний ланцюжок файлів із двох областей — глобальної та проєктної. Усе склеюється в один спільний контекст, і пріоритет вирішує позиція в ланцюжку: що пізніше файл, то він головніший.

Область 1. Проєкт: від кореня вниз до поточної папки

Codex визначає корінь проєкту (зазвичай це корінь git-репозиторію) і йде вниз по дереву папок до вашої поточної робочої директорії. У кожній папці по шляху він перевіряє наявність файлу: спершу AGENTS.override.md, потім AGENTS.md, потім запасні імена з налаштування project_doc_fallback_filenames. Останнє — налаштовуваний список альтернативних імен файлу інструкцій (наприклад, TEAM_GUIDE.md чи .agents.md); за замовчуванням він не заданий, і Codex шукає лише AGENTS.md. З кожної папки береться не більше одного файлу.

Далі — найважливіше, що пропускають майже всі гайди. Codex склеює знайдені файли від кореня вниз, розділяючи їх порожнім рядком. Файли, що ближче до вашої поточної папки, ідуть у зібраному промпті пізніше — і тому перекривають те, що було вище. «Ближче до задачі = головніше».

BINANCE SIMPLE EARNЗмусь крипту працюватиВідсотки на USDT і BTC без блокування — гроші лишаються під рукою.Розмістити

Розберемо на конкретному дереві монорепозиторію:

myproject/
├── AGENTS.md              ← правила всього репозиторію
├── apps/
│   └── web/
│       └── AGENTS.md      ← правила лише фронтенду
└── services/
    └── api/
        └── AGENTS.md      ← правила лише бекенду

Якщо ви запускаєте задачу всередині apps/web/, Codex збере ланцюжок: спершу myproject/AGENTS.md, потім apps/web/AGENTS.md. Правила фронтенду йдуть останніми й перекривають загальні там, де конфліктують (наприклад, корінь каже «форматуй через Prettier», а apps/web уточнює свою конфігурацію). Файл services/api/AGENTS.md у цю задачу взагалі не потрапить — він не на шляху від кореня до поточної папки.

Наскільки це реальний, а не теоретичний механізм: у власному репозиторії OpenAI (openai/codex) — 88 файлів AGENTS.md, по одному на пакети й підсистеми. Це і є каскадна модель у роботі — загальні правила в корені, точкові в підпапках.

Область 2. Глобальний рівень: ~/.codex

Крім проєкту, Codex читає глобальний файл у своїй домашній папці — за замовчуванням ~/.codex (каталог можна перевизначити змінною CODEX_HOME). Тут Codex бере перший непорожній файл: спершу перевіряє AGENTS.override.md, якщо його немає — AGENTS.md.

Глобальний файл — для ваших особистих звичок на всі проєкти: як ви любите оформлювати фінальну відповідь, чи питати перед комітом, загальний тон спілкування. Проєктні файли — для того, що має сенс лише в конкретному репозиторії: команди, структура, домовленості команди.

Важливий момент про пріоритет, який майже ніде не проговорюють: глобальний файл іде в спільному ланцюжку першим і тому має найнижчий пріоритет. Проєктні файли (навіть кореневий AGENTS.md) додаються після нього й перекривають глобальні правила там, де вони сперечаються. Тобто особиста звичка з ~/.codex/AGENTS.md працює за замовчуванням, але конкретний проєкт може її перевизначити.

AGENTS.override.md — заміна файлу свого рівня, а не всього ланцюжка

Звичайні AGENTS.md по дереву складаються. Але іноді в конкретній папці треба не додати правило поверх базового AGENTS.md, а замінити його. Для цього є AGENTS.override.md. Якщо Codex знаходить такий файл у директорії, він бере на цьому рівні лише його й ігнорує сусідній AGENTS.md у тій самій папці. Важливо: це заміна на рівні однієї директорії, а не скасування всього, що вище — батьківські файли (наприклад, кореневий AGENTS.md) так само беруть участь у ланцюжку. На глобальному рівні override зручний для тимчасової заміни: поклали ~/.codex/AGENTS.override.md, попрацювали в іншому режимі, видалили — повернулася звичайна спільна інструкція. Нічого стирати не довелося.

Ліміт розміру: 32 KiB

Codex складає файли ланцюжка не нескінченно. Щойно сумарний розмір зібраних інструкцій упирається в project_doc_max_bytes (за замовчуванням 32 KiB), Codex перестає додавати наступні файли. Порожні файли він пропускає. Практичний висновок: роздутий на десятки кілобайт AGENTS.md небезпечний не тим, що «багато літер», а тим, що частина інструкцій може мовчки не вміститися в контекст. Про це — у розділі про ризики.

Як створити AGENTS.md: команда /init

Руками файл створювати не обов’язково. У Codex CLI є команда /init — за описом із документації вона «створює файл AGENTS.md з інструкціями для Codex». Запускаєте /init у корені репозиторію, агент оглядає проєкт і генерує стартовий файл: структуру, виявлені команди, базові домовленості. Це зручна заготовка, але не фінал — згенерований чернетку майже завжди треба дочистити під реальні домовленості команди.

Поряд у CLI є споріднені команди, що знадобляться при налаштуванні: /status (показати поточну конфігурацію сесії), /permissions (обрати, що Codex дозволено робити), /model (модель і рівень reasoning), /review (рев’ю змін). За замовчуванням Codex CLI працює на моделі gpt-5.6-sol у режимі medium (дані на 17 липня 2026 — імена моделей у OpenAI змінюються часто, перевіряйте актуальні в /model).

Що писати в AGENTS.md — і чого не писати

Добрий AGENTS.md — це не переказ README і не список благих побажань. Це виконувані правила: те, що агент може взяти й застосувати дослівно. Починати варто з короткого seed-файлу на 12–20 рядків і розширювати його лише коли спливає повторювана проблема, а не заливати одразу гігантський шаблон.

Ось що реально працює і що витрачає намарно ліміт та увагу агента:

Подивитися, як це виглядає на великому проєкті, можна прямо у вихідниках Codex: у AGENTS.md репозиторію openai/codex трапляються рядки на кшталт «Не запускай cargo test напряму — використовуй just test, щоб прогін ішов за правилами репозиторію» і «Тримай модулі Rust менші за 500 рядків, не рахуючи тестів». Це рівно той жанр — конкретне правило, яке агент може перевірити, а не побажання.

Готовий шаблон-приклад AGENTS.md

Стартовий seed, з якого зручно почати (замініть команди й шляхи на свої):

# AGENTS.md

## Стек і структура
- Node.js 20 + TypeScript, пакетний менеджер — pnpm.
- Код застосунку: src/. Тести: tests/. Не чіпай build/ і dist/.

## Команди
- Встановлення: pnpm install
- Тести: pnpm test (ганяй після правок у src/)
- Лінт: pnpm lint (обов'язковий перед PR)
- Збірка: pnpm build

## Межі
- Не змінюй файли в migrations/ без явної задачі.
- Не додавай прод-залежності без підтвердження.
- Секрети беремо з .env, у код не хардкодимо.

## Pull request
- Один PR — одна задача. В описі: що і навіщо.
- Перед PR: pnpm lint && pnpm test — обидва зелені.

## Готово, коли
- Тести проходять, лінт чистий, задача з тікета закрита.

Двадцять рядків закривають переважну більшість випадків, коли агент «робить не те». Далі дописуйте по факту — побачили, що Codex знову оступився в одному місці, додали правило саме про нього.

AGENTS.md, config.toml і системний промпт — три різні шари

Ще одне джерело плутанини: у Codex є кілька місць, де щось «налаштовується», і їх постійно змішують. Насправді це три незалежні шари з різними ролями.

Найпростіше запам’ятати так: системний промпт — це «характер» агента, який ви не змінюєте; AGENTS.md відповідає на питання «що робити в цьому проєкті»; config.toml — «як технічно запускати» (яка модель, що агенту дозволено, мережа, пісочниця). Налаштування config.toml і підключення зовнішніх інструментів через MCP — окремі теми, вони не про цей файл; тут важливе одне: правила поведінки живуть у AGENTS.md, а не в конфізі.

AGENTS.md — це відкритий стандарт, а не фішка Codex

Легко подумати, що AGENTS.md — приватний формат OpenAI. Це не так, і це змінює цінність вкладення у файл. AGENTS.md — відкритий формат, яким за даними agents.md (на липень 2026) користується понад 60 000 open-source проєктів. Він виріс зі спільних зусиль екосистеми (OpenAI Codex, Amp, Google Jules, Cursor, Factory) і зараз курується Agentic AI Foundation під егідою Linux Foundation.

Практичний сенс: той самий AGENTS.md розуміють понад двадцять різних агентів — Codex, Cursor, GitHub Copilot, Gemini CLI, Devin, Windsurf, Amp, Aider та інші. Ви пишете правила проєкту один раз, а не окремий файл під кожен інструмент. Для команди, де різні розробники сидять на різних агентах, це заощаджує і час, і розсинхрон правил. (Claude Code у цей список не входить — у нього своя конвенція, файл CLAUDE.md; про нього — нижче в порівнянні.)

Це ж корисно й не-програмісту, який збирає продукт зі ШІ: підхід «вайб-кодингу» працює надійніше, коли агент діє за записаними межами, а не за усним проханням у чаті, яке він забуде до наступної сесії.

Де AGENTS.md ламається: ризики та граблі

Розділ, якого немає в більшості гайдів «усе завжди працює». Ось реальні ризики та граблі AGENTS.md.

• Файл роздули — частина правил не доїхала. Ліміт project_doc_max_bytes (32 KiB) не абстрактний: щойно сумарний ланцюжок AGENTS.md його перевищує, Codex перестає додавати файли. У великому монорепо з десятком рівнів це реально. Тримайте файли короткими; загальне — у корені, часткове — у підпапках.
• Секрети у файлі. AGENTS.md іде в контекст моделі й майже завжди комітиться в git. Ключі, паролі й токени туди писати не можна — це витік. Секрети — у .env і в системах секретів, а в AGENTS.md щонайбільше «бери ключі зі змінних оточення».
• Застарілі команди небезпечніші за їх відсутність. Якщо у файлі написана команда тестів, якої вже немає, агент чесно спробує її виконати й зламається або зробить не те. AGENTS.md — частина коду: застарів — виправте, інакше він шкодить.
• Гасла замість правил. «Пиши якісно» агент не може перевірити й по суті ігнорує. Працюють лише правила з командою чи конкретною межею: не «роби тести добре», а «після правок у src/ ганяй pnpm test».
• Конфлікт файлів без розуміння пріоритету. Якщо правила кореня й підпапки сперечаються, перемагає найближчий до задачі. Пишете суперечливі інструкції на різних рівнях, не пам’ятаючи про це, — отримуєте «агент робить не те, що в корені». Тримайте перевизначення свідомими.

Як перевірити, що AGENTS.md завантажився

Не гадайте — спитайте агента напряму. Офіційна документація рекомендує з кореня репозиторію виконати:

codex --ask-for-approval never "Summarize the current instructions."

Codex перелічить інструкції, які реально потрапили в контекст, у порядку пріоритету. Якщо у відповіді є ваші правила (команда тестів, заборонена папка) — файл підхопився. Якщо чогось немає — перевірте ім’я файлу, шлях і чи не вперлися ви в ліміт 32 KiB.

FAQ

Де має лежати файл AGENTS.md? У корені репозиторію — це база для всього проєкту. Для окремих модулів кладіть додаткові AGENTS.md у їхні підпапки: Codex візьме найближчий до вашої поточної директорії й накладе його поверх кореневого. Особисті правила на всі проєкти — у ~/.codex/AGENTS.md.

Чим AGENTS.md відрізняється від config.toml? AGENTS.md описує, що агенту робити в проєкті: правила, команди, стиль, межі. config.toml задає, як запускати Codex технічно: модель, режим схвалення, пісочницю, профілі. Перший — інструкція для агента, другий — налаштування інструмента. Це різні файли з різними задачами.

Чи обов’язково писати AGENTS.md вручну? Ні. Команда /init у Codex CLI згенерує стартовий AGENTS.md за вашим репозиторієм. Але згенерований файл — чернетка: його варто скоротити до реальних правил команди, а не лишати як є.

Що буде, якщо AGENTS.md занадто великий? Codex складає файли, доки не впреться в project_doc_max_bytes (за замовчуванням 32 KiB), і потім перестає додавати наступні. Частина інструкцій може не потрапити в контекст. Тому файли тримають короткими, а специфіку виносять у AGENTS.md підпапок.

Чи працюватиме цей файл не лише в Codex? Так. AGENTS.md — відкритий формат, його читають понад двадцять агентів, включно з Cursor, GitHub Copilot, Gemini CLI та Devin. Один файл описує правила проєкту для всіх інструментів одразу, окремий під кожен агент не потрібен. Виняток — Claude Code: у нього своя конвенція, файл CLAUDE.md.

Що важливіше при конфлікті — кореневий AGENTS.md чи файл у підпапці? Файл ближче до вашої поточної папки. Codex склеює ланцюжок від кореня вниз, і глибші файли йдуть пізніше, перекриваючи загальні правила там, де вони сперечаються. Тому загальне тримають у корені, а уточнення — у підпапках.