Как написать файл AGENTS.md для ИИ-агентов, работающих с кодом
Напишите короткий AGENTS.md с командами установки и тестов, правилами и границами, настройте его загрузку в Claude Code и Gemini CLI и проверьте на небольшой задаче.
AGENTS.md — это обычный Markdown-файл в корне репозитория, который объясняет агентам для кода, как работать с проектом: какие команды запускать, где лежит код и что не трогать. Обязательных разделов в нём нет. Держите его коротким, делайте каждое правило проверяемым и убедитесь, что каждый агент его загружает.
В этом руководстве: что включить в файл, шаблон, как Claude Code и Gemini CLI находят файл, и быстрая проверка. Те же шаги работают, когда вы запускаете агентов с телефона через Mono от Reunified.
1. Решите, что должно быть в файле
Сайт agents.md называет этот файл README для агентов. Включите факты, которые нужны каждой сессии, и пропустите всё, что агент может узнать из кода.
| Добавьте в AGENTS.md | Не добавляйте |
|---|---|
| Команды установки, тестов и линтинга | Пароли, API-ключи и токены |
| Где лежит основной код | Полное дерево файлов или список зависимостей |
| Соглашения, которые отличаются от общепринятых | Длинные процедуры (лучше дайте ссылку на документ) |
| Файлы, которые нельзя править, и действия, о которых нужно сначала спросить | Личные предпочтения (для них есть пользовательский файл агента) |
В монорепозитории можно добавить AGENTS.md в каждый пакет. Приоритет у ближайшего файла, а прямая инструкция в чате перекрывает его.
2. Начните с короткого шаблона
Вот вымышленный пример для «tidy-recipes», веб-приложения на TypeScript, которое использует pnpm:
# AGENTS.md
## Overview
TypeScript web app for saving recipes. Components live in src/components.
## Setup
- `pnpm install`
## Test and lint
- `pnpm test` and `pnpm lint`
## Code style
- TypeScript only. One component per file.
## Boundaries
- Never edit db/migrations/.
- Ask before adding a dependency.
## Before you finish
- Run `pnpm test` and `pnpm lint`.
- List the files you changed and the test results.Указывайте только те команды, которые вы сами запускали в этом репозитории. Агент поверит и неверной.
3. Пишите правила, которые агент может проверить
Хорошее правило позволяет потом проверить, выполнил ли его агент.
| Расплывчато | Конкретно |
|---|---|
| Тестируй свои изменения | Запусти pnpm test и pnpm lint перед завершением |
| Поддерживай порядок в файлах | Компоненты размещай в src/components |
| Будь осторожен с базой данных | Никогда не правь db/migrations/ |
| Подведи итог работы | Перечисли изменённые файлы и результаты тестов |
Формулируйте границы как правила «никогда» и «сначала спроси», по одному на строку.
4. Настройте чтение файла в Claude Code и Gemini CLI
Сайт agents.md перечисляет Codex, Gemini CLI, opencode и других агентов, которые поддерживают этот формат, но некоторым сначала нужна настройка.
По умолчанию последние версии Claude Code читают AGENTS.md, только если в рабочей папке или выше нет CLAUDE.md, .claude/CLAUDE.md или CLAUDE.local.md (см. его документацию о памяти). Если один из этих файлов у вас есть или версия старая, импортируйте AGENTS.md из CLAUDE.md. В проекте tidy-recipes есть старый CLAUDE.md, поэтому добавьте в его начало эту строку, а заметки только для Claude оставьте ниже:
@AGENTS.md
Prefer small commits.Начните новую сессию, выполните /context и проверьте, что CLAUDE.md есть в разделе Memory files. Если CLAUDE.md нет, команда /memory вместо этого показывает путь к AGENTS.md.
Gemini CLI по умолчанию читает GEMINI.md. Чтобы добавить AGENTS.md, запишите это в файл .gemini/settings.json проекта (см. его документацию о GEMINI.md):
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}Начните новую сессию и выполните /memory show, чтобы увидеть, что загрузилось. Для других агентов смотрите их документацию.
5. Проверьте файл на небольшой задаче
В новой сессии дайте агенту такую задачу:
Сначала перечисли загруженные правила проекта и файл, из которого взято каждое. Затем замени текст кнопки «Save recipe» на «Save» в src/components/SaveButton.tsx. Больше ничего не меняй.
Сверьте результат с файлом:
- Агент назвал AGENTS.md (или CLAUDE.md с импортом).
- Он выполнил
pnpm testиpnpm lintи сообщил результаты. - Он не тронул db/migrations/ и не добавил зависимостей.
- Он перечислил изменённые файлы.
Проверьте правку сами с помощью git diff (см. проверку изменений кода от ИИ). Если агент не может назвать правило, файл, скорее всего, не загрузился, так что вернитесь к шагу 4. Если он назвал правило, но не выполнил его, сделайте правило конкретнее.
6. Держите файл коротким и актуальным
Документация Claude Code советует держать CLAUDE.md короче 200 строк: длинные файлы занимают больше контекста, и агент следует им менее надёжно. Стремитесь к тому же с AGENTS.md. Что происходит, когда контекст заполняется, описано в руководстве по контекстному окну.
Обновляйте файл, когда агент повторяет ошибку, и удаляйте устаревшие команды и противоречащие друг другу правила. Добавляйте его в коммиты и проверяйте изменения в нём так же, как код.
Файл лишь направляет агента и ничего не может запретить. Чтобы заблокировать действие, используйте настройки разрешений агента или отклоните его запрос (см. руководство по разрешениям инструментов).
В Mono агент запускается в рабочей папке проекта на вашем компьютере и ищет эти файлы там. AGENTS.md, CLAUDE.md или .gemini/settings.json можно открыть в редакторе Mono, в том числе с телефона, и правки сохраняются сами. Чтобы создать файл, попросите агента или откройте терминал с карточки проекта. Mono не проверяет файл и не влияет на то, какой файл загружает агент. Mono пока недоступен, но вы можете записаться в список ожидания.
