Що таке AGENTS.md. Файл Markdown без обов'язкових полів, який читають Codex, Cursor і Copilot
AGENTS.md це README для AI-агентів, які пишуть код. Що в нього вписати, де він лежить, як працюють файли в підпапках і які інструменти його читають.
Частина посібникаClaude Code, повний посібник. Від встановлення до власних скілів і плагінів
У цьому тексті
Коротко
AGENTS.md це звичайний файл Markdown у головній папці репозиторію, де записують інструкції для AI-агентів, які пишуть код. Обов'язкових полів у ньому нема, у великому проєкті таких файлів може бути кілька, і перевагу має той, що найближче до коду, який змінюють. Його читають, зокрема, Codex, Cursor, Gemini CLI і агент GitHub Copilot.
Новий програміст отримує доступ до репозиторію й одразу запускає AI-агента. Агент не знає, як тут запускають тести, тому вгадує, запускає не ту команду й чверть години лагодить те, що й не було зламане. Один рядок у файлі AGENTS.md усе це прибрав би. Це найкоротша відповідь на питання, що таке AGENTS.md.
Цей текст належить до нашого посібника з Claude Code. Факти ми перевірили на сторінках авторів формату й інструментів, станом на 10 листопада 2026.
Що таке AGENTS.md і навіщо його писати
Сайт формату agents.md називає його README для агентів. README пишуть для людей. Він описує проєкт, каже, як почати, і не має тонути в деталях. AGENTS.md пишуть для AI-агентів, які пишуть код. Сюди йде те, що в README заважало б. Команди для збирання й тестів, стиль коду, правила для pull request.
Це відкритий формат, а не функція одного виробника. За даними agents.md, його використовують понад 60 тисяч проєктів з відкритим кодом, а опікується ним Agentic AI Foundation при Linux Foundation.
Для фірми, яка замовляє код або має свого програміста, сенс простий. Правила проєкту записують один раз, і кожен AI-інструмент, який їх читає, починає роботу з тим самим знанням. Не треба переписувати їх в окремий файл для кожної програми.
Який формат має AGENTS.md
Ніякого особливого. Це звичайний Markdown без обов'язкових полів і без заголовків, які треба використати. Агент читає текст так само, як людина. Важливо, щоб інструкції були конкретні й можна було перевірити, чи їх виконано.
Сайт формату радить почати з команд для тестів. Якщо вони є у файлі, агент спробує їх запустити й виправити помилки, перш ніж вважатиме задачу закінченою. Файл має жити разом з проєктом, тож його правлять щоразу, коли в проєкті щось змінюється.
Так може виглядати AGENTS.md для вигаданого проєкту, магазину кави на Laravel і Vue.
# Магазин Зерно
Laravel 12 і Vue 3. Адмінпанель лежить у `resources/js/admin`.
## Запуск
- `composer install` і `npm install` після клонування
- `php artisan serve` і `npm run dev` запускають сайт локально
## Тести
- `php artisan test` перед кожним комітом
- `npm run lint` після кожної зміни у файлах Vue
- Кожне виправлення помилки отримує тест, який її відтворює
## Стиль коду
- Відступи 4 пробіли в PHP і 2 пробіли у Vue
- Тексти для клієнтів тільки в `lang/uk.json`
- Нові таблиці в базі тільки через міграції
## Pull request
- Заголовок у форматі `[shop] короткий опис`
- Не змінюй файли в `config/payments` без питанняТут нема опису фірми й прохань про «чистий код». Агент сам бачить код. Файл каже йому тільки те, чого з коду не прочитаєш.
Де лежить AGENTS.md і що з файлами в підпапках
Головний файл лежить у головній папці репозиторію. У великому репозиторії з кількома застосунками можна додати окремий AGENTS.md у папку кожного з них. Правило з сайту формату просте. Агент читає файл, найближчий до коду, який він змінює, тож файл із підпапки має перевагу над головним. Пряма вказівка в чаті перемагає будь-який файл.
Деталі в різних інструментах різні. Найточніше їх описує OpenAI в документації Codex.
| Що | Як це робить Codex |
|---|---|
| Глобальний файл | ~/.codex/AGENTS.md для всіх проєктів |
| Перевизначення | AGENTS.override.md замість AGENTS.md |
| Порядок | від кореня репозиторію вниз до поточної папки |
| Об'єднання | файли склеюються, ближчий до поточної папки йде пізніше |
| Ліміт | 32 KiB разом, параметр project_doc_max_bytes |
З таблиці випливає одна практична річ. Codex бере з кожної папки щонайбільше один файл, а коли сума дійде до ліміту, наступні файли вже не додаються. Розлогий AGENTS.md швидко його з'їдає, тому краще писати коротко.
Codex дозволяє також вважати інструкціями файли з іншими назвами. Їх дописують у ~/.codex/config.toml, а файли поза цим списком Codex пропускає.
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536Хто читає AGENTS.md
Сайт agents.md перелічує інструменти, які підтримують формат. Серед них Codex від OpenAI, Jules і Gemini CLI від Google, Cursor, Windsurf, Devin, Aider, Zed, Warp, VS Code, Junie від JetBrains і агент GitHub Copilot. Повний список на сайті довший.
Двом інструментам з цього списку потрібен один рядок налаштувань. В Aider дописують read: AGENTS.md у файл .aider.conf.yml. У Gemini CLI вказують AGENTS.md як файл контексту в .gemini/settings.json.
Claude Code у списку нема. Але документація Anthropic описує, що від версії 2.1.277 Claude Code сам читає AGENTS.md, якщо в проєкті нема файлу CLAUDE.md. Коли саме так стається і як тримати обидва файли в злагоді, ми описали в тексті AGENTS.md і CLAUDE.md. Про сам CLAUDE.md є текст CLAUDE.md, як його написати, а готові шаблони лежать у прикладах CLAUDE.md.
AGENTS.md це інструкція, а не замок
Агент читає AGENTS.md і намагається його дотримуватися, але це текст для моделі, а не замок. Anthropic прямо пише, що такі файли Claude сприймає як контекст, а не як обов'язкові налаштування. Рядок «не чіпай файли оплат» нікого не зупинить, якщо агент вирішить інакше. Те, що має бути справді заблоковане, налаштовують у дозволах конкретного інструмента. Для Claude Code ми описали це в тексті про дозволи.
AGENTS.md потрапляє в репозиторій, тож його бачить кожен, хто має доступ. Паролі, ключі API й адреси внутрішніх серверів туди не пишуть.
Для початку досить файлу з чотирма розділами, як у прикладі вище. Далі дописуйте одне речення щоразу, коли агент удруге робить ту саму помилку.
Якщо хочете знати, де AI може зняти роботу з вашої фірми, замовте безкоштовний аудит AI. Ми переглянемо ваші задачі й скажемо, з чого почати.
Документація до теми
Що хочете змінити у своїй фірмі?
Залиште номер. Поговоримо про ваш процес і перевіримо, чи можемо допомогти. Перша розмова безкоштовна.
Послуга, про яку цей текст
Автоматизація та AI / OCRАвтоматизація переписування документів, OCR і правила перевірки, а дані лишаються у вас.