AGENTS.md: Один файл контексту для кожного агента кодування (Codex, Antigravity, Claude)

Ви провели післяобідній час, пишучи чистий CLAUDE.md. Ваш агент нарешті перестав вгадувати ваш стек і почав запускати правильну команду тестування. Потім ваш колега відкриває той самий репозиторій з Codex, ви пробуєте Antigravity CLI на бічній гілці, і жоден з цих важко здобутих контекстів не переноситься. Кожен інструмент хоче свій власний файл, у своєму власному місці.

AGENTS.md є відповіддю на цей безлад: один простий Markdown файл, у корені вашого репозиторію, який будь-який агент кодування читає перед тим, як торкнутися вашого коду.

Що таке AGENTS.md насправді

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

Це відкрита конвенція, яку вже читає Codex і зростаючий список агентських інструментів, з явною метою бути портативною між ними. Один файл, багато агентів, замість одного спеціального файлу для кожного інструменту.

AGENTS.md проти CLAUDE.md проти GEMINI.md

Коли цей посібник писався вперше, кожен інструмент шукав власний файл. Відтоді більшість із них зійшлися на AGENTS.md:

• Codex читає AGENTS.md, як і GitHub Copilot CLI, Cursor, Amp та більшість нових агентських CLI.
• Claude Code читає CLAUDE.md, а починаючи з версії 2.1.277 сам читає й AGENTS.md, коли у вашій робочій папці та папках вище немає ні CLAUDE.md, ні CLAUDE.local.md. Коли CLAUDE.md існує, Claude читає лише його, хіба що ви зміните налаштування Project instructions у /config.
• Antigravity CLI читає AGENTS.md або GEMINI.md, у корені репозиторію чи в будь-якій підпапці, а ще папку .agents/rules/ і глобальні правила в ~/.gemini/.

Зміст майже ідентичний у всіх трьох: контекст проекту, команди, конвенції. Досі відрізняється інше: який файл обирає інструмент, коли знаходить кілька. Саме тому дублювання тих самих правил у трьох файлах вручну - це програшна гра (більше про підтримку їх у синхронізації нижче). Ми перевірили цю поведінку 10 жовтня 2026 року за документацією Claude Code про пам'ять і документацією Antigravity про правила.

Якщо ви працюєте переважно в Claude Code, наш посібник CLAUDE.md детально описує специфічну структуру Claude. AGENTS.md - це нейтральний до постачальника аналог цього файлу.

Що в нього включити

Тримайте його коротким і з високим сигналом. Агент читає це на кожному завданні, тому кожен рядок змагається за увагу. Основні моменти:

• Стек, в одному диханні. "Next.js 16, TypeScript, Prisma, MariaDB." Ніякої історії, ніякого маркетингу.
• Команди, які мають значення. Як встановити, запустити, зібрати, протестувати і перевірити. Точні команди: npm test, а не "запустіть тести."
• Конвенції. Іменування, розташування файлів, обробка помилок, шаблони, які ви дійсно застосовуєте в огляді.
• Карта директорій. Два рядки про те, де що знаходиться, щоб агент перестав бездумно шукати.
• Правила "прочитай перед зміною". "Прочитайте docs/payments.md перед редагуванням чого-небудь у billing/." Ця одна звичка запобігає багатьом проблемам.
• Жорсткі заборони. "Ніколи не створюйте гілку без запиту." "Ніяких абсолютних шляхів до машин у зафіксованих файлах."

Помилки, які змушують агентів ігнорувати його

Файл контексту не видає помилок. Агент просто відхиляється. Звичайні причини:

1. Занадто довгий. Файл на 600 рядків ховає п'ять правил, які мають значення. Відріжте все, що агент може вивести з самого коду.
2. Протиріччя. "Завжди пишіть тести" в одному розділі, "пропускайте тести для прототипів" в іншому. Агент обирає одне випадково.
3. Машинно-специфічні шляхи. /Users/you/project/... у зафіксованому файлі ламає для кожного колеги і для кожного агента на кожній іншій машині. Тримайте шляхи відносними.
4. Застарілі команди. Команда тестування змінилася шість місяців тому, файл - ні. Тепер агент запускає неправильну команду з повною впевненістю.
5. Відсутність пріоритетів. Все "важливе", тому нічого не є важливим. Поставте незаперечні речі першими і позначте їх.
6. Скидання документації. Це інструкції, а не вікі. Посилайтеся на ваші документи, не вставляйте їх.

Підтримка одного контексту між постачальниками

Ось практична частина, яку більшість посібників пропускає. Якщо ви або ваша команда використовуєте більше одного агентського CLI, ви не хочете мати три різні копії тих самих правил.

Два чистих підходи:

• Один AGENTS.md, і більше нічого. Якщо нікому не потрібні правила лише для Claude, тримайте один AGENTS.md: його читають і Codex, і Antigravity CLI, і Claude Code 2.1.277 та новіші. Пастка непомітна: CLAUDE.md або особистий CLAUDE.local.md, доданий пізніше, змушує Claude Code перестати читати AGENTS.md.
• Один канонічний файл, один імпорт. Тримайте все в AGENTS.md, почніть CLAUDE.md з рядка @AGENTS.md, а нижче напишіть правила лише для Claude. Claude спочатку читає імпортований файл. Наш власний репозиторій влаштований саме так: його CLAUDE.md складається з цього одного рядка. Символьне посилання (ln -s AGENTS.md CLAUDE.md) теж працює, але погано у Windows: там для його створення потрібні права адміністратора або режим розробника, а клон без core.symlinks отримує замість ваших інструкцій текстовий файл з одного рядка.

У будь-якому випадку правило те саме: пишіть контекст один раз, а не один раз на постачальника. Це також єдиний спосіб, як він залишається правильним, тому що один файл - це єдиний файл, який люди дійсно підтримують.

Коли ви запускаєте кілька агентів одночасно

Рівень репозиторію AGENTS.md відповідає на питання "що це за проект". Він не відповідає на питання "хто цей агент". Коли ви запускаєте агента Backend, агента Frontend і агента QA паралельно на одному коді, кожен з них потребує спільного контексту проекту плюс свою власну роль.

Це рівень, який AgentsRoom додає поверх вашого AGENTS.md. Кожен агент отримує присвячену роль зі своїм власним системним підказом (DevOps, Frontend, Security та інші), тому спільний файл залишається компактним, але кожен агент все ще знає свою роботу. Це незалежно від постачальника за задумом, тому та сама установка запускає Claude, Codex або Antigravity поруч, і ваші повторювані інструкції живуть у Бібліотеці підказок замість того, щоб їх переписувати в кожній сесії.

Коли ви досягнете цього моменту, метод запуску кількох агентів паралельно без втрати контролю є природним наступним читанням.

Висновок

Напишіть один AGENTS.md. Тримайте його коротким, актуальним, портативним. Спрямуйте кожен інструмент на нього замість того, щоб підтримувати файл для кожного агента. Ваш контекст перестає бути прив'язаним до того CLI, з якого ви почали, і ваші агенти, які б ви не запускали, починають з однієї сторінки.

Хочете, щоб кожен агент був на одному екрані, кожен зі своєю роллю та вашим спільним контекстом? Завантажте AgentsRoom, підключіть свого постачальника і запустіть ваш флот у роботу.

Часті запитання

Що таке AGENTS.md?

Файл Markdown, зазвичай у корені репозиторію, який агенти кодування завантажують як постійні інструкції перед початком роботи: що це за проект, як його збирати й тестувати, яких конвенцій дотримуватися і яких пасток уникати. Це відкрита конвенція, спільна для різних інструментів, а не файл якогось одного з них. Його читають Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp і, починаючи з версії 2.1.277, Claude Code.

Чи читає Claude Code AGENTS.md?

Так, починаючи з Claude Code 2.1.277, але лише тоді, коли у вашій робочій папці та вище немає ні CLAUDE.md, ні .claude/CLAUDE.md, ні CLAUDE.local.md. Тоді він завантажує кожен AGENTS.md від робочої папки вгору, а також AGENTS.md підпапки, коли відкриває в ній файл. Якщо CLAUDE.md існує, Claude читає лише його, хіба що ви перемкнете Project instructions на claude-md-and-agents-md у /config. У старіших версіях додайте рядок @AGENTS.md на початок CLAUDE.md.

Antigravity використовує AGENTS.md чи GEMINI.md?

Обидва. Antigravity читає AGENTS.md, GEMINI.md або папку .agents/rules/ у корені репозиторію чи в будь-якій підпапці, а також глобальні правила з ~/.gemini/. Правила підсумовуються, а не замінюють одне одного, і коли два з них суперечать одне одному, перемагає правило конкретнішої папки.

Що залишити: AGENTS.md чи CLAUDE.md?

Залиште AGENTS.md єдиним файлом, який ви підтримуєте. Якщо вам потрібні ще й правила лише для Claude, додайте CLAUDE.md, перший рядок якого @AGENTS.md, і напишіть ці правила під ним: Claude спочатку читає імпортований файл. Якщо такі правила не потрібні, для Claude Code 2.1.277 і новіших вистачить одного AGENTS.md. Уникайте двох повних копій тих самих правил: та, яку ніхто не редагує, застаріває.

Де має лежати AGENTS.md?

У корені репозиторію, для правил, які діють скрізь. Claude Code і Antigravity також читають файли AGENTS.md у підпапках, тож пакет або сервіс із власними командами може мати власний файл, який читається, коли агент працює в цій папці.