AGENTS.md і HUMAN.md: що це та як їх писати

Що таке AGENTS.md

AGENTS.md — це звичайний markdown-файл у корені репозиторію, який містить інструкції для агента програмування щодо роботи з цим проєктом. На офіційному сайті його описано як «README для агентів: спеціально призначене передбачуване місце для надання контексту та інструкцій, які допомагають агентам програмування на основі ШІ працювати над вашим проєктом». Формат розвиває Agentic AI Foundation у межах Linux Foundation. Станом на July 2026 його читають понад twenty агентів, зокрема Codex, Cursor, Jules, Devin і GitHub Copilot.

Ця конвенція має практичне обґрунтування. Новий учасник команди читає README, припускає, яку команду збірки потрібно виконати, а якщо припущення неправильне — запитує когось. Агент не може поставити запитання. Він припускає, запускає npm test у проєкті, де використовується pnpm test, читає повідомлення про помилку й пробує щось інше. Ви платите за кожен із цих токенів. Якщо один раз записати правильну команду, можна усунути весь цей клас помилок.

Обов’язкових полів немає. На сайті це прямо зазначено: «AGENTS.md — це просто стандартний Markdown. Використовуйте будь-які потрібні заголовки; агент просто аналізує наданий вами текст». Це вся специфікація. Цінність не у форматі. Вона полягає в тому, що файл розміщено за шляхом, який кожен інструмент уже перевіряє.

Куди розміщувати файл і який файл має пріоритет

Розмістіть перший файл у корені репозиторію. У монорепозиторії можна додати інші файли до кожного підпроєкту. Правило просте: «agents автоматично читає найближчий файл у дереві каталогів, тому пріоритет має найближчий файл». Якщо два файли конфліктують, перевагу має файл, який відповідає редагованому об’єкту. Усе, що ви вводите в чаті, має пріоритет над обома файлами.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Вкладеність варто використовувати, оскільки це єдиний спосіб задати правило, яке діє в одній папці, але не діє в наступній. Правило на кшталт «кожна кінцева точка перевіряє вхідні дані» слід розмістити поруч із кінцевими точками. У кореневому файлі воно завантажується під час кожного стороннього завдання і не дає жодної користі.

Що слід указати в AGENTS.md

Запишіть те, чого агент не може визначити з коду. Спочатку наведіть точні команди для збирання, тестування та перевірки стилю — у вигляді, у якому їх можна вставити в термінал. Додайте команду для запуску одного тесту, оскільки агент, який знає лише команду для всього набору тестів, запустить увесь набір сорок разів. Укажіть правила, що відрізняються від стандартних налаштувань інструментів: агент уже знає стандартні правила, тому йому потрібно повідомити лише про ваші відхилення. Додайте формат повідомлень комітів і правила для pull request, якщо вони у вас є.

Формулюйте правила достатньо конкретно, щоб їх можна було перевірити. «Використовуйте відступи у 2 пробіли» — придатна інструкція, оскільки можна перевірити, виконано її чи ні. «Правильно форматуйте код» — ні, оскільки це неможливо перевірити. Те саме стосується розташування файлів: «Обробники API зберігаються в src/api/handlers/» краще, ніж «підтримуйте впорядковану структуру файлів».

Негативні правила також важливі. «Ніколи не редагуйте файли в dist/, їх створює npm run build» запобігає конкретній помилці. Оскільки в правилі вказано причину, агент зможе визначити аналогічні випадки, які ви не описали.

Чого ніколи не слід додавати до такого файлу

Ніколи не зберігайте секрети в цих файлах. Файл фіксується в git, завантажується в контекст на початку кожного сеансу та надсилається постачальнику моделі під час кожного запиту. API key у AGENTS.md залишається в історії вашого репозиторію та в журналах стороннього постачальника. Замість вставляння секрету вкажіть, де його знайти: «пароль до бази даних міститься у .env; цей шлях додано до gitignore. Перш ніж читати його, запитайте дозволу». Ширший підхід описано в розділі як не допустити доступу агента до облікових даних.

Не додавайте інформацію, яку агент може отримати самостійно під час перегляду. Вставлений список каталогів, копія списку залежностей або опис архітектури, що лише повторює назви каталогів, застаріють уже через тиждень після написання. Водночас вони споживають контекст під час кожного сеансу. Залишайте потенційні проблеми та причини. Не додавайте перелік вмісту.

CLAUDE.md — аналог AGENTS.md для Claude Code

Claude Code читає CLAUDE.md і самостійно не читає AGENTS.md. Файл проєкту розміщується в ./CLAUDE.md або ./.claude/CLAUDE.md, особисті налаштування для всіх проєктів — у ~/.claude/CLAUDE.md, а організація може розгорнути загальносистемний файл у /etc/claude-code/CLAUDE.md в Linux. Виявлені файли об’єднуються від кореня файлової системи до робочого каталогу, тому файл, розташований найближче до каталогу, з якого запущено сеанс, читається останнім.

Якщо у вашому репозиторії вже є AGENTS.md, не створюйте другу копію. Імпортуйте його, а потім додайте лише специфічні для Claude відомості:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Символічне посилання підходить, якщо вам не потрібно нічого додавати:

ln -s AGENTS.md CLAUDE.md

У разі успіху команда нічого не виводить. У наступному сеансі виконайте /context і переконайтеся, що CLAUDE.md відображається в розділі Файли пам’яті. Якщо цього файла немає в списку, його не було завантажено, тому його вміст не застосовувався. Щоб створити початковий варіант замість написання файла вручну, виконайте /init: команда аналізує кодову базу та створює початковий файл, а якщо CLAUDE.md уже існує, пропонує вдосконалення, не перезаписуючи його.

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

Окремо наголосимо на одному моменті. AGENTS.md містить рекомендації, а не є системою дозволів. Його вміст надходить як звичайний контекст, тому модель читає його і зазвичай дотримується інструкцій, але ніщо не блокує дію, що їм суперечить. Для правила, яке має виконуватися щоразу, наприклад «ніколи не виконуй push до main», використовуйте hook або налаштування дозволів, оскільки вони виконуються як код і не залежать від того, чи вирішить модель дотримуватися правила.

Інструменти, які створюють ці файли замість вас

Два проєкти зі списку популярних на GitHub станом на 30 July 2026 показують, у якому напрямку розвивається ця практика.

agent0ai/dox (1,368 зірок станом на July 2026) — це framework для підтримання дерева файлів AGENTS.md в актуальному стані. Він не постачається як package і не має runtime. Скопіюйте вміст його AGENTS.md у власний кореневий AGENTS.md — це і є встановлення. Для вже наявного проєкту повідомте своєму agent:

Initialize DOX tree for this project now.

Після цього agent створює дочірні файли AGENTS.md та їхні індекси, переглядає це дерево перед кожним редагуванням і оновлює відповідну документацію після внесення змін. Основне припущення полягає в тому, що документація, яку agent підтримує як побічний результат своєї роботи, залишається актуальною, а документація, яку людина оновлює вручну, — ні.

HUMAN.md: той самий підхід, спрямований на вас

Intuition-Lab/personal-model (1,260 зірок станом на July 2026) застосовує цей підхід до людини, а не до репозиторію. Проєкт описує ваш HUMAN.md як результат роботи системи, а не файл, який ви вводите вручну: «живу модель того, що зараз має значення, як ви зазвичай ухвалюєте рішення та куди спрямовується ваша увага». Він працює локально в macOS 13 або новішої версії, збирає дані про активність після надання дозволу macOS і надає результат агентам через MCP (model context protocol). Короткий спосіб встановлення:

uv tool install personal-model
persome onboard
persome model open --after 30

Щоб отримати більшість переваг, це не потрібно. Написаний вручну HUMAN.md містить приблизно двадцять рядків: вашу роль, часовий пояс, стек, який ви фактично використовуєте, рішення, які ви вже ухвалили й не хочете переглядати повторно, а також бажаний обсяг пояснень у відповідях. Він усуває те саме повторне пояснення, яке усуває файл проєкту, але на рівень вище.

Є важливе застереження. HUMAN.md є профілем людини, тому за визначенням містить конфіденційні дані. Не зберігайте його в публічному репозиторії. Розмістіть його в ~/.claude/CLAUDE.md або у файлі CLAUDE.local.md, доданому до gitignore, у корені проєкту. Такий файл завантажується разом із файлом, що зберігається в репозиторії, і обробляється так само.

Початковий шаблон, який можна скопіювати

Цей шаблон навмисно короткий. Видаліть розділи, які не застосовуються, і не додавайте розділи, актуальність яких не зможете підтримувати.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

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

FAQ

Чи є AGENTS.md тим самим файлом, що й CLAUDE.md?

Це одна й та сама концепція у двох файлах із різними назвами. Claude Code читає CLAUDE.md і ігнорує AGENTS.md, якщо не налаштувати зв’язок між ними. Залиште один файл основним і зв’яжіть із ним інший: додайте на початку CLAUDE.md рядок @AGENTS.md або скористайтеся ln -s AGENTS.md CLAUDE.md. За місяць дві окремі повні копії почнуть відрізнятися.

Чи гарантує створення AGENTS.md, що агент дотримуватиметься його вмісту?

Ні. Вміст передається як контекст, тому модель його читає і зазвичай дотримується цих вказівок, але ніщо не блокує дію, яка їм суперечить. Нечіткі вказівки виконуються найменш надійно, а якщо два файли містять протилежні вказівки, агент довільно обирає одну з них. Для правила, яке має виконуватися щоразу, використовуйте hook або правило дозволів. Клієнт застосовує їх незалежно від рішення моделі.

Чи слід додавати AGENTS.md до git?

Так, якщо файл містить відомості, актуальні для проєкту: команди збирання, структуру та угоди. У цьому і полягає призначення файла: агенти ваших колег починають роботу з тим самим контекстом, що й ваш агент. Особисті відомості або налаштування, специфічні для одного комп’ютера, зберігайте в окремому файлі, доданому до gitignore. Облікові дані не повинні зберігатися ні в одному з цих файлів.

Що таке HUMAN.md і чи потрібен він мені?

HUMAN.md — це машиночитний профіль людини, а не проєкту. У ньому зберігаються ваша роль, ваші обмеження та рішення, які ви вже ухвалили, щоб не переглядати їх під час кожного сеансу. Для початку не потрібні спеціальні інструменти: двадцять рядків, написаних вручну у файлі інструкцій на рівні користувача, дають більшість переваг. Розглядайте цей файл як персональні дані та не додавайте його до репозиторію, який публікуєте.