AGENTS.md и CLAUDE.md: постоянные инструкции для ИИ-агента

ИИ-ассистент в редакторе каждый раз начинает с чистого листа: он не помнит, что тесты запускаются через composer test, что в проекте запрещены новые зависимости, а миграции нельзя менять задним числом. Повторять это в каждом чате утомительно, и рано или поздно вы забудете важное. Поэтому у агентов появились файлы постоянных инструкций — промты, которые лежат в репозитории и подгружаются в начале каждой сессии. Статья о том, какие это файлы, что в них писать и как добиться, чтобы агент действительно им следовал.

Какие бывают файлы#

Форматы почти одинаковые: обычный Markdown без обязательных полей. Разница — в том, какой инструмент какой файл читает.

AGENTS.md авторы формата называют «README для агентов». README пишется для людей, а в AGENTS.md уходит то, что людям читать скучно, а агенту нужно: команды сборки, правила тестов, соглашения. Список поддерживающих инструментов большой и растёт; некоторым (например, Aider и Gemini CLI) чтение файла нужно включить в настройках.

CLAUDE.md — файл Claude Code. При этом Claude Code умеет читать и AGENTS.md: по умолчанию — когда в проекте нет CLAUDE.md. Если нужны оба, можно подключить AGENTS.md из CLAUDE.md импортом (строка @AGENTS.md), и одна инструкция будет работать для всех инструментов.

Copilot читает .github/copilot-instructions.md для всего репозитория, а файлы *.instructions.md с полем applyTo в шапке — только для файлов, подходящих под маску. Агент Copilot тоже понимает AGENTS.md.

Что писать#

Рекомендации у всех трёх источников сходятся. В файле должно быть то, что агент не может быстро узнать сам, но без чего ошибётся.

1. Что за проект: одним абзацем — назначение, язык, фреймворк, версии.
2. Команды: установка, сборка, тесты, линтер, запуск — проверенные, в правильном порядке. GitHub отдельно советует указывать версии инструментов и известные проблемы сборки с обходными путями.
3. Стиль и соглашения: то, что не видно из кода или отличается от привычного.
4. Где что лежит: конфигурация, главные модули, CI.
5. Запреты и опасные места: что нельзя трогать, где легко сломать безопасность.
6. Правила изменений: формат коммитов и pull request, что проверить перед сдачей.

Пример для небольшого PHP-проекта:

# Учёт заявок

Внутренний сайт учёта заявок. PHP 8.2 (код должен работать и на 8.4),
PostgreSQL 15, без фреймворков и Composer-пакетов.

## Команды
- Тесты: `php tests/run.php` (все должны проходить перед сдачей).
- Проверка синтаксиса: `php -l` для каждого изменённого файла.
- Схема БД: `db/schema.sql`. Изменения — только новой миграцией в `db/migrations/`.

## Код
- Точка входа — `public/index.php`, маршруты — `src/routes.php`.
- Запросы к БД — только через `Db::query()` с параметрами, без склейки строк.
- Вывод в HTML — только через `e()`.
- Интерфейс на русском, код и комментарии на английском.

## Нельзя
- Добавлять внешние библиотеки (решение заказчика).
- Менять применённые миграции.
- Придумывать требования: если их нет — записать вопрос в `docs/QUESTIONS.md`
  и спросить в чате.

Как писать, чтобы агент следовал#

Конкретно и проверяемо. В документации Claude Code хорошая пара примеров: вместо «правильно форматируй код» — «отступ 2 пробела», вместо «тестируй изменения» — «запускай npm test перед коммитом», вместо «держи файлы в порядке» — «обработчики API лежат в src/api/handlers/». Расплывчатое правило агент не может выполнить, потому что не знает, что вы имели в виду.

Коротко. Файл загружается в каждую сессию и занимает контекст. Anthropic советует держать CLAUDE.md в пределах 200 строк, GitHub — около двух страниц. Длинный файл не только дорогой: чем он больше, тем хуже агент следует отдельным правилам. Импорты из других файлов помогают навести порядок, но не уменьшают объём — импортированное загружается целиком.

Без противоречий. Если в одном месте «пиши тесты на Pest», а в другом «используй PHPUnit», агент выберет одно наугад. Перечитывайте инструкции, когда проект меняется, и удаляйте устаревшее.

С причиной. «Не добавляй зависимости — на сервере нет доступа к packagist» работает лучше голого запрета: агент поймёт, что и npm install в этом проекте плохая идея.

Структурно. Заголовки и короткие списки читаются лучше сплошного текста — и людьми, и моделями.

Начните с генерации. В Claude Code команда /init изучит проект и создаст черновик CLAUDE.md с найденными командами и соглашениями. Дальше остаётся дописать то, что из кода не видно.

Вложенные файлы и приоритеты#

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

• AGENTS.md можно положить в каждую подпапку-проект. Агент читает ближайший файл по дереву папок, и он важнее общих правил. Явная просьба в чате важнее любого файла.
• CLAUDE.md из текущей папки и всех папок выше загружаются вместе, не заменяя друг друга; более близкий к рабочей папке читается последним. Файлы из подпапок подгружаются, когда агент начинает работать с файлами там. Для правил по типам файлов есть .claude/rules/ с полем paths в шапке.
• Личные настройки отделяйте от общих: CLAUDE.local.md (добавьте в .gitignore) или ~/.claude/CLAUDE.md для всех проектов. Туда — ваши тестовые адреса и привычки, которые не нужны команде.

Инструкция — не гарантия#

Файл инструкций — это контекст, а не настройка, которую нельзя нарушить. Документация Claude Code говорит об этом прямо: если действие нужно запретить при любых обстоятельствах, используйте механизмы, которые срабатывают независимо от модели, — хуки, права доступа, проверки в CI. Правило «никогда не пушь в main» в AGENTS.md полезно, но защищённая ветка в репозитории надёжнее.

Ещё одна ловушка — файлы инструкций из чужих репозиториев. Агент выполнит указания из AGENTS.md, который вы склонировали вместе с проектом. Перед работой с незнакомым репозиторием загляните в эти файлы: это тоже входные данные, подробнее — в статье «Prompt injection: как защитить приложение с ИИ».

Набор промтов для этапов работы#

Для долгих задач — переписать модуль, перенести проект на новую базу — одного файла правил мало. Хорошо работает такая схема:

• AGENTS.md — постоянные правила: стек, решения заказчика, запреты, как задавать вопросы;
• PROGRESS.md — план и статус этапов, его ведёт агент;
• prompts/01-….md, prompts/02-….md — задание на каждый этап: что прочитать, что сделать, какой результат и критерии готовности.

Тогда каждый этап начинается новым чатом с короткой командой «Прочитай AGENTS.md и выполни prompts/03-….md», а агент не тащит за собой историю прошлых этапов и не забывает правила.

Чек-лист#

Источники#

• AGENTS.md — описание формата.
• How Claude remembers your project — документация Claude Code.
• Adding repository custom instructions for GitHub Copilot — GitHub Docs.