Що таке Agents.md і як ним користуватися?
Автор: Редакція Domeny.ForSale Опубліковано
Коротко: AGENTS.md — це текстовий файл з інструкціями для агентів AI, які працюють над проєктом, найчастіше над кодом. Він описує, зокрема, як запускати тести, як організовано проєкт і за якими правилами вносити зміни. Сам файл нічого не запускає: його дія залежить від того, чи читає його використовуваний інструмент і як тлумачить наведені в ньому вказівки.
Для чого потрібен файл AGENTS.md
Агент AI — це інструмент, який не лише відповідає на запитання, а й може виконувати завдання, наприклад переглядати файли, редагувати код і запускати команди. Для цього йому потрібен контекст конкретного проєкту. Без нього агент може вибрати невідповідний спосіб установлення залежностей або змінити файли, які команда не редагує вручну.
AGENTS.md дає змогу зберегти цей контекст у репозиторії — місці зберігання коду та історії його змін. Файл використовує Markdown — простий текстовий формат, що підтримує заголовки, списки й блоки коду. Його можна редагувати у звичайному редакторі та переглядати разом з іншими змінами в проєкті.
Це домовленість про спосіб передавання інструкцій, а не програма, модель AI чи механізм надання прав доступу. Запис «не змінюй конфігурацію виробничого середовища» є вказівкою для агента, але технічно не блокує доступу до цієї конфігурації.
AGENTS.md і README — різні завдання документації
README.md зазвичай знайомить людину з проєктом: пояснює його призначення, установлення та основи використання. AGENTS.md зосереджується на тому, як агент має працювати в конкретному репозиторії. Обидва файли можуть доповнювати один одного, а не дублювати ту саму документацію.
Наприклад, README бібліотеки може показувати, як використати її у власному застосунку. Натомість інструкції для агента можуть вимагати після зміни публічного інтерфейсу оновити приклади та запустити певний набір тестів.
Не слід також плутати AGENTS.md із llms.txt — файлом, який пропонують як спосіб надання мовним моделям інформації про вміст сайту. AGENTS.md стосується передусім роботи над проєктом, а не представлення вмісту сайту. Його наявність не означає, що сайт буде видимим у пошукових системах чи сервісах AI.
Де розмістити файл і чи кожен інструмент його прочитає
Зазвичай файл розміщують у кореневому каталозі репозиторію. Створюючи його, використовуйте назву AGENTS.md з великими літерами: у системах, що розрізняють регістр, Agents.md може бути іншим файлом. Не припускайте, що інструмент розпізнає будь-який варіант назви.
У більших проєктах трапляються додаткові файли AGENTS.md у підкаталогах, наприклад окремо для інтерфейсу користувача та серверної частини. Це дає змогу розділити правила для різних технологій. Однак сфера дії інструкцій і спосіб розв’язання суперечностей залежать від інструмента, тому не варто вважати, що всі агенти використовують однакову ієрархію інструкцій.
Перш ніж запроваджувати цей файл, перевірте в офіційній документації агента, яким користуєтеся:
- чи підтримує він
AGENTS.mdі чи потребує додаткового налаштування; - у яких каталогах шукає інструкції;
- чи читає файли з підкаталогів;
- як поєднує їх із запитом користувача та іншими інструкціями.
Саме лише додавання файлу до репозиторію не означає, що кожна функція AI у редакторі почне його використовувати.
Що записати в інструкціях для агента
Найкорисніша інформація — та, що зменшує потребу здогадуватися: конкретні команди, розташування важливих файлів і межі дорученої зміни. Загальна порада «пиши якісний код» не пояснює агенту, як перевірити результат.
Приклад файлу для проєкту на JavaScript, що використовує npm, може виглядати так. Ці команди доречні лише тоді, коли відповідають конфігурації конкретного репозиторію:
## Робота над проєктом
## Запуск і перевірка
- Установлюй залежності командою `npm ci`.
- Запускай тести командою `npm test`.
- Перевіряй дотримання правил коду командою `npm run lint`.
- Якщо не можеш виконати перевірку, вкажи причину.
## Організація файлів
- Код застосунку міститься в `src/`.
- Не редагуй вручну каталог `generated/`.
## Межі змін
- Не додавай залежностей без підтвердження користувача.
- Виправляючи помилку, додай тест, який її відтворює.
- Не поєднуй виправлення з не пов’язаним із ним упорядкуванням коду.
У проєкті з кількома застосунками вкажіть, із якого каталогу потрібно запускати кожну команду. Якщо для тестів потрібен додатковий сервіс, опишіть цю вимогу та безпечний спосіб підготовки середовища. Не додавайте до інструкцій паролів, токенів чи інших секретів.
Як перевірити ефективність і підтримувати актуальність
Доброю перевіркою буде невелике завдання, наприклад виправлення валідації одного поля форми. Спостерігайте, чи агент використовує належні команди, не змінює автоматично згенеровані файли та повідомляє про тести, які не виконав. Якщо інструмент показує завантажені інструкції, перевірте й цю інформацію.
Коли агент припуститься помилки, спершу з’ясуйте, чи прочитав він файл. Додавання нових заборон не допоможе, якщо проблема полягає у відсутності підтримки файлу або його неправильному розташуванні. Якщо інструкцію було прочитано, замініть нечітке формулювання конкретною дією чи умовою.
Ставтеся до AGENTS.md як до частини документації, яку потрібно підтримувати: оновлюйте його після змін команд, структури каталогів і процесу тестування. Забезпечуйте обмеження доступу за допомогою прав і налаштувань середовища, а не лише речень у файлі. Для початку запишіть робочі команди перевірки та найважливіші обмеження, а потім перевірте їх на одному невеликому завданні.
Дивіться також: Що таке GitHub?
Читайте також
