AGENTS.md і HUMAN.md: пояснення та шаблон

Що таке AGENTS.md

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

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

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

Де розміщується файл і який файл має пріоритет

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

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

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

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

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

Що ніколи не має міститися в такому файлі

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

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

CLAUDE.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 відображається в розділі Memory files. Якщо цього запису немає в списку, файл не завантажився, тому його вміст не застосовувався. Щоб згенерувати перший варіант замість ручного створення файлу, виконайте /init. Команда аналізує кодову базу й створює початковий файл. Якщо CLAUDE.md уже існує, вона пропонує покращення, а не перезаписує його.

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

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

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

Два проєкти зі списку GitHub Trending від 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 містить приблизно twenty рядків: вашу роль, часовий пояс, стек, який ви фактично використовуєте, рішення, які вже ухвалені й не потребують повторного обговорення, а також бажаний обсяг пояснень у відповідях. Він заощаджує той самий час на повторному поясненні, який заощаджує файл проєкту, але на рівень вище.

Є один нюанс. 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.

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

FAQ

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

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

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

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

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

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

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

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