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

Зараз ландшафт розділений за інструментами:

• CLAUDE.md - це те, що шукає Claude Code.
• GEMINI.md - це конвенція Antigravity CLI.
• AGENTS.md - це стандарт між інструментами, який читають Codex та інші, розроблений як нейтральний.

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

Якщо ви працюєте переважно в 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.md та GEMINI.md однорядковими файлами, які кажуть "дивіться AGENTS.md", або створіть символьні посилання. Одне джерело правди, кожен інструмент отримує.
• Один файл, спільний за конвенцією. Якщо ваші інструменти можуть бути спрямовані на користувацький шлях, направте їх усі на AGENTS.md і видаліть решту.

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

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

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

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

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

Висновок

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

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