Що таке AGENTS.md. Файл Markdown без обов'язкових полів, який читають Codex, Cursor і Copilot

AGENTS.md це README для AI-агентів, які пишуть код. Що в нього вписати, де він лежить, як працюють файли в підпапках і які інструменти його читають.

Частина посібникаClaude Code, повний посібник. Від встановлення до власних скілів і плагінів

У цьому тексті
  1. Що таке AGENTS.md і навіщо його писати
  2. Який формат має AGENTS.md
  3. Де лежить AGENTS.md і що з файлами в підпапках
  4. Хто читає AGENTS.md
  5. AGENTS.md це інструкція, а не замок

Коротко

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.

AGENTS.md
# Магазин Зерно

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. Ми переглянемо ваші задачі й скажемо, з чого почати.

Документація до теми

Що хочете змінити у своїй фірмі?

Залиште номер. Поговоримо про ваш процес і перевіримо, чи можемо допомогти. Перша розмова безкоштовна.

Коли зручно зателефонувати?
Адміністратор: Oleksandr Bondarenko (BondSoft)Політика конфіденційностіРегламент
Юридичні деталі

Адміністратором даних є Oleksandr Bondarenko, що веде господарську діяльність під фірмою Oleksandr Bondarenko Software Solutions (BondSoft), ul. Jana Heweliusza 11, 80-890 Gdańsk, NIP 5833576264, e-mail: office@bondsoft.pl.

Дані обробляємо виключно з метою контакту у справі вашого запиту та надання пропозиції — на підставі вашої згоди (ст. 6 ч. 1 п. a RODO та ст. 398 закону Prawo komunikacji elektronicznej) і нашого правомірного інтересу, що полягає в опрацюванні запиту (ст. 6 ч. 1 п. f RODO).

Надання даних добровільне, але необхідне для зворотного контакту. Згоду можете відкликати будь-коли, написавши на office@bondsoft.pl — це не впливає на законність обробки до відкликання.

Ви маєте право на доступ до даних, їх виправлення, видалення, обмеження обробки, перенесення, а також на скаргу до Голови Управління охорони персональних даних.

Повна інформація: Політика конфіденційності.

Напишіть на пошту

Послуга, про яку цей текст

Автоматизація та AI / OCR

Автоматизація переписування документів, OCR і правила перевірки, а дані лишаються у вас.