AGENTS.md и HUMAN.md: что это и как использовать

Что такое AGENTS.md

AGENTS.md — это обычный файл в формате Markdown в корне репозитория. В нем описано, как агент для работы с кодом должен работать с проектом. На официальном сайте этот файл описан как «README для агентов: выделенное предсказуемое место для предоставления контекста и инструкций, которые помогают агентам для работы с кодом на основе ИИ работать с вашим проектом». Формат курирует Agentic AI Foundation при Linux Foundation. Более двадцати агентов читают этот файл, включая Codex, Cursor, Jules, Devin и GitHub Copilot (по состоянию на July 2026).

Причина появления этого соглашения носит практический характер. Новый участник команды читает 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

Укажите то, что агент не может определить по исходному коду. Сначала приведите точные команды сборки, тестирования и проверки стиля в формате, в котором их можно вставить в терминал. Добавьте команду для запуска одного теста. Если агент знает только команду для запуска всего набора, он запустит весь набор сорок раз. Укажите соглашения, которые отличаются от настроек инструментов по умолчанию. Агент уже знает настройки по умолчанию, поэтому ему нужно сообщить только об отличиях. Добавьте формат сообщений коммитов и правила для запросов на слияние, если они у вас есть.

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

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

Что никогда не должно в них находиться

Никогда не помещайте секреты в эти файлы. Файл фиксируется в git, загружается в контекст в начале каждого сеанса и передается поставщику модели при каждом запросе. Ключ API в AGENTS.md остается ключом API в истории вашего репозитория и в журналах третьей стороны. Вместо вставки секрета укажите ссылку на него: «пароль базы данных находится в .env, этот файл исключен из git; запросите разрешение перед чтением». Более подробно этот принцип рассматривается в разделе как не допускать доступа агента к учетным данным.

Не включайте сведения, которые агент может получить самостоятельно. Вставленный список каталогов, копия списка зависимостей, описание архитектуры, повторяющее названия каталогов, — все это устаревает уже через неделю после написания и тем временем увеличивает объем контекста при каждом сеансе. Оставляйте сведения о проблемах и их причинах. Убирайте перечень содержимого.

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 содержит рекомендации, а не реализует систему разрешений. Его содержимое передается как обычный контекст. Модель читает его и обычно соблюдает указания, но ничто не блокирует действие, противоречащее этим указаниям. Для правила, которое должно соблюдаться каждый раз, например «никогда не отправлять изменения в main», используйте hook или настройку разрешений. Они выполняются как код и не зависят от решения модели соблюдать правило.

Инструменты, которые создают эти файлы за вас

Два проекта из списка популярных репозиториев GitHub по состоянию на 30 July 2026 показывают направление развития этого соглашения.

agent0ai/dox (1,368 stars по состоянию на 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 lines: в нем указываются ваша роль, часовой пояс, фактически используемый стек, решения, которые вы уже приняли и не хотите пересматривать, а также требуемый объем объяснений в ответах. Он устраняет необходимость постоянно повторять одни и те же пояснения, как файл проекта, но на уровень выше.

Есть одно важное ограничение. HUMAN.md содержит профиль человека, поэтому по определению относится к конфиденциальным данным. Не храните его в публичном репозитории. Разместите его в ~/.claude/CLAUDE.md или в игнорируемом Git файле CLAUDE.local.md в корне проекта. Такой файл загружается вместе с отслеживаемым файлом и обрабатывается таким же образом.

Стартовый шаблон для копирования

Шаблон специально сделан коротким. Удалите неприменимые разделы и не добавляйте разделы, которые не сможете поддерживать в актуальном состоянии.

# 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 — это машиночитаемый профиль человека, а не проекта. В нем указываются ваша роль, ограничения и решения, которые вы уже приняли, чтобы не пересматривать их на каждом сеансе. Для начала не нужны специальные инструменты: двадцати строк, написанных вручную в файле пользовательских инструкций, достаточно для получения большей части пользы. Считайте этот файл персональными данными и не добавляйте его в репозиторий, который публикуете.