Что такое AGENTS.md и зачем нужен файл HUMAN.md

Что такое AGENTS.md

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

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

Вложенность стоит использовать, так как это единственный способ задать правило, которое верно для одной папки, но ложно для другой. Правило вроде «каждый endpoint проверяет свои входные данные» должно находиться рядом с самими endpoint. Если поместить его в корневой файл, оно будет загружаться для каждой несвязанной задачи и не принесет пользы. Если ваш корневой файл уже разросся до раздела на каждый сервис, разделение на вложенную структуру решит проблему; там же описано, какие правила следует перенести вниз, а какие оставить в корне.

Что должно содержаться в AGENTS.md

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

Символическая ссылка (symlink) подходит, если вам нечего добавить:

ln -s AGENTS.md CLAUDE.md

При успешном выполнении команда ничего не выводит. В следующей сессии запустите /context и убедитесь, что CLAUDE.md отображается в разделе Memory files. Если файла нет в этом списке, значит, он не был загружен и содержащиеся в нем инструкции не применились. Чтобы создать черновик вместо написания файла вручную, запустите /init: инструмент проанализирует кодовую базу и создаст начальный файл, а если CLAUDE.md уже существует, он предложит улучшения, а не перезапишет его.

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

Один момент заслуживает особого внимания. AGENTS.md — это руководство, а не система прав доступа. Содержимое файла поступает как обычный контекст, поэтому модель считывает его и обычно соблюдает, но ничто не блокирует действие, которое ему противоречит. Если написанное вами правило игнорируется и вы не понимаете почему, изучите причины, по которым инструкция может быть проигнорирована, прежде чем переписывать формулировку в третий раз. Для правил, которые должны соблюдаться всегда, например «никогда не делайте push в main», используйте хуки или настройки прав доступа, так как они работают на уровне кода и не зависят от того, решит ли модель подчиниться.

Инструменты для автоматического создания этих файлов

Два проекта из списка трендов GitHub на 30 июля 2026 года показывают, в каком направлении развивается этот стандарт.

agent0ai/dox (1,368 звезд на июль 2026 года) — это фреймворк для поддержания актуальности дерева файлов AGENTS.md. Он не поставляет пакеты или среду выполнения. Вы копируете содержимое его AGENTS.md в свой корневой AGENTS.md, и на этом установка завершена. Для уже существующего проекта вы даете своему агенту следующую команду:

Initialize DOX tree for this project now.

Затем агент создает дочерние файлы AGENTS.md и их индексы, обходит дерево перед внесением любых правок и обновляет соответствующую документацию после того, как изменения вступают в силу. Основная идея заключается в том, что документация, которую агент поддерживает как побочный эффект своей работы, остается достоверной, в то время как документация, которую человек правит вручную, — нет.

HUMAN.md, тот же трюк применительно к вам

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

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

Вам не нужно ничего из этого, чтобы получить основную пользу. HUMAN.md, написанный вручную, занимает около 20 строк: ваша роль, часовой пояс, стек, который вы реально используете, решения, которые вы уже приняли и не хотите пересматривать, а также объем пояснений, который вы хотите получать в ответ. Это избавляет от тех же повторяющихся объяснений, что и файл проекта, только на уровень выше.

Одно предостережение. 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, если вы не свяжете их между собой. Выберите один файл в качестве основного источника информации и сделайте ссылку на него в другом: добавьте строку @AGENTS.md в начало вашего CLAUDE.md или используйте ln -s AGENTS.md CLAUDE.md. Две полные копии, которые поддерживаются раздельно, неизбежно начнут противоречить друг другу в течение месяца.

Гарантирует ли создание AGENTS.md, что агент будет следовать инструкциям?

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

Нужно ли добавлять AGENTS.md в git?

Да, если информация актуальна для проекта: команды сборки, структура, соглашения. В этом и заключается смысл файла, так как агенты ваших коллег начнут работу с тем же контекстом, что и ваш. Все личное или специфичное для конкретной машины должно находиться в отдельном файле, исключенном из git, а учетные данные не должны попадать ни в один из них.

Что такое HUMAN.md и нужен ли он мне?

HUMAN.md — это машиночитаемый профиль человека, а не проекта. Он содержит вашу роль, ограничения и уже принятые решения, чтобы к ним не приходилось возвращаться каждую сессию. Вам не нужны специальные инструменты для начала работы: двадцати строк, написанных вручную в файле инструкций пользовательского уровня, будет достаточно для получения основной пользы. Относитесь к этому как к персональным данным и не добавляйте файл в репозитории, которые вы отправляете на сервер.