AGENTS.md и CLAUDE.md: как написать конфиг-файл, которым агент реально пользуется

Хорошо написанный конфиг-файл — самый эффективный и малозатратный шаг в агентном программировании. Настроили контекст один раз — и каждая сессия выигрывает: агент перестаёт угадывать команду запуска тестов, перестаёт переформатировать код по своим умолчаниям, перестаёт заходить в директорию, которую вы запретили трогать. Эта страница — конкретная механика за AI-native-навыком «контекст и конфигурация», одним из 17 AI-native-навыков, которые мы оцениваем на каждом уровне. Хранить устойчивую проектную память в CLAUDE.md / AGENTS.md — характерный признак Level 3 Agentic Developer, поэтому стоит разобраться основательно.

Основная идея одна для всех инструментов, хотя механика различается: конфиг-файл несёт то, что агент не может вывести из самого кода. Модель уже знает ваш язык программирования. Она не знает, что ваши тесты требуют конкретного флага, что три месяца назад вы ушли с определённой библиотеки или что infra/ — сгенерированный каталог, который нельзя редактировать вручную. Именно этот пробел и закрывает файл.

Обзор инструментов: одна философия, разные файлы

Каждый крупный агент читает файл проектного контекста. Философия у всех общая, а вот имена файлов и механика загрузки различаются. Вот карта на 2026 год:

Файл	Инструмент(ы)	Статус
AGENTS.md	OpenAI Codex, Cursor, GitHub Copilot agent, + ~20 инструментов	Открытый кросс-инструментальный стандарт
CLAUDE.md	Claude Code	Родной формат Claude Code
GEMINI.md	Gemini CLI	Родной формат Gemini
.github/copilot-instructions.md	GitHub Copilot	Инструкции для репозитория Copilot
.cursor/rules (ранее .cursorrules)	Cursor	Формат правил Cursor

Вывод: AGENTS.md — складывающийся единый источник истины, открытая спецификация, которую уже читают ~20 инструментов. Но есть нюанс: Claude Code не читает AGENTS.md нативно — только CLAUDE.md. Поэтому канонический паттерн «один источник» выглядит так: держите AGENTS.md как основной файл и подключите его к Claude крошечным CLAUDE.md с импортом:

@AGENTS.md

<!-- Ниже можно добавить заметки, специфичные для Claude -->

Симлинк тоже работает (ln -s AGENTS.md CLAUDE.md), но на Windows лучше используйте @import — симлинки там требуют прав администратора. В итоге поддерживаете один файл, а оба экосистемных инструмента его читают.

Что туда класть

Гитхабовский анализ более 2500 репозиториев («How to write a great AGENTS.md») показал: конфиги, которые реально помогают агентам, имеют шесть общих разделов. В порядке убывания важности:

1. Команды — размещаются в начале, с точными командами и флагами (npm test, npm run build, pytest -v), не просто названиями инструментов. Это самый высокоэффективный раздел: агент уже знает, что pytest существует; он не знает обязательных флагов вашего проекта. Ставьте в начало.
2. Практики тестирования — как вы тестируете, что запускать перед коммитом, требования к покрытию.
3. Структура проекта — где что лежит, чтобы агент не искал.
4. Стиль кода — покажите один реальный фрагмент кода, а не три абзаца текста.
5. Git-workflow — именование веток, соглашения о коммитах, правила для PR.
6. Границы — что агент никогда не должен трогать (сгенерированные каталоги, секреты, вендорный код, миграции).

Обратите внимание на порядок. «Команды с флагами» — первые не случайно: это то, что модель наиболее надёжно не может угадать и наиболее часто делает неправильно. Если напишете только одно хорошо — напишите это.

Включать / исключать: тест для каждой строки

Документация Anthropic по memory проводит чёткую двухколоночную границу. Используйте её как фильтр для каждой строки, которую хотите добавить.

Включать	Исключать
Bash-команды, которые агент не может угадать	Всё, что выводится из кода
Правила оформления, отличающиеся от умолчаний	Стандартные соглашения языка, которые модель и так знает
Инструкции по тестированию / предпочтительный тест-раннер	Подробная документация по API (лучше дать ссылку)
Этикет репозитория (именование веток, правила PR)	Часто меняющаяся информация
Специфические для проекта архитектурные решения	Длинные объяснения и туториалы
Особенности среды разработки (нужные env-переменные)	Пофайловые описания кодовой базы
Неочевидные подводные камни	Самоочевидные практики вроде «пишите чистый код»

Есть один тест, который сворачивает всю таблицу в привычку:

Тест для каждой строки: «Если убрать эту строку, агент начнёт делать ошибки? Если нет — вырежи её.»

Применяйте к каждой строке. «Используйте TypeScript» — агент видит .ts-файлы, вырежьте. «Запускайте миграции базы данных командой npm run db:migrate, никогда не редактируйте migrations/ вручную» — он не мог это угадать, и ошибка здесь повредит данные; оставьте.

Пишите на правильном уровне абстракции

Рекомендации Anthropic по контекстной инженерии сводят хорошее авторство к четырём принципам.

1. Конкретность / проверяемость. Формулируйте правила достаточно конкретно, чтобы проверить их по поведению агента. Размытые указания нельзя верифицировать — значит, им нельзя следовать надёжно.

• «Отступ 2 пробела» — не «Форматируйте код правильно».
• «Запускайте npm test перед коммитом» — не «Тестируйте изменения».
• «HTTP-обработчики лежат в src/api/handlers/» — не «Держите файлы в порядке».

2. Правильный уровень абстракции. Держитесь между жёсткой логикой и расплывчатыми советами: «достаточно конкретно, чтобы направлять поведение, достаточно гибко, чтобы быть сильной эвристикой». Слишком жёстко — сломается на первом крайнем случае; слишком размыто — ничем не поможет.

3. Минимально достаточно. «Минимально» — не значит «коротко». Это значит: дать ровно столько контекста, чтобы агенту не пришлось угадывать или переоткрывать — и ни слова больше. Вырезайте наполнитель, оставляйте несущие детали.

4. Структура. Используйте помеченные разделы — заголовки Markdown или XML-теги. Файл, который легко просматривать, — файл, который агент (и коллеги по команде) реально парсит.

Держите файл компактным

Главная причина оставаться лаконичными — бюджет токенов. Конфиг-файл загружается целиком в каждую сессию. Он не подгружается по запросу — он дописывается к контексту при запуске. Поэтому раздутость имеет прямую, измеримую цену: раздутый CLAUDE.md измеримо снижает точность следования инструкциям. Формулировка Anthropic прямолинейна — раздутые файлы CLAUDE.md заставляют Claude игнорировать ваши реальные инструкции. Каждая мусорная строка ослабляет хорошие.

Ориентиры конкретны:

• Anthropic ставит мягкую цель — не более ~200 строк для CLAUDE.md.
• Codex применяет жёсткий лимит 32 KiB для AGENTS.md (project_doc_max_bytes); всё, что превышает лимит, обрезается — то есть часть файла просто не загружается.

Ещё одна ловушка: импорты не экономят бюджет. @imported-файл всё равно загружается в контекст при запуске — вы разбили файл, но не уменьшили его объём. Чтобы реально сократить, что загружается в каждую сессию, выносите условно нужное содержимое:

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

Принцип тот же, что и у «теста для каждой строки», но на уровне разделов: если что-то нужно лишь иногда — этому не место в файле, который загружается всегда.

DESIGN.md: командная конвенция, не стандарт

DESIGN.md — хрестоматийный пример принципа «держи конфиг компактным, линкуй детали». Это отдельный документ по дизайну/архитектуре — ключевые решения, доменная модель, архитектурные паттерны, почему всё сделано именно так — который AGENTS.md @imports или на который ссылается, вместо того чтобы вставлять всё внутрь. Это оставляет всегда загружаемый конфиг коротким, а глубокий контекст — в одном переходе.

Но будьте честны насчёт статуса: в отличие от AGENTS.md и CLAUDE.md, нет первичного источника, который закрепил бы DESIGN.md как стандартный файл агентной конфигурации. Это мощная командная конвенция, а не задокументированный стандарт. Используйте, потому что это работает для вашей команды, а не потому что так требует спецификация.

Область действия и иерархия

Оба подхода слоями загружают файлы — от широкого к конкретному, но приоритет разрешается по-разному.

У CLAUDE.md четыре области действия, загрузка от широкой к конкретной:

1. Управляемая политика — задаётся организацией / IT, применяется на уровне всей организации.
2. Пользовательская — ~/.claude/CLAUDE.md, действует для всех ваших проектов.
3. Проектная — ./CLAUDE.md, добавляется в git и используется командой.
4. Локальная — ./CLAUDE.local.md, в gitignore, для личных переопределений.

В монорепозиториях файлы в родительских каталогах загружаются автоматически, а в дочерних — по запросу. Импорты используют синтаксис @путь/к/файлу (относительный или абсолютный), вложенность до 4 уровней, при этом парсер пропускает блоки кода — путь внутри блока не считается импортом.

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

Мост между двумя системами, описанный выше, связывает их воедино: держите AGENTS.md как основной, добавьте CLAUDE.md с @AGENTS.md — и ваша иерархия становится общей для всех инструментов без дублирования.

Рекомендательный, а не принудительный характер

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

Акцентирующие слова вроде IMPORTANT и YOU MUST измеримо улучшают точность следования, но не гарантируют её. Для требований, которые должны выполняться каждый раз (запустить форматтер, заблокировать коммит с упавшими тестами, никогда не писать в main), детерминированный барьер — это хуки (в Claude Code), а не более жёсткие формулировки в конфиге.

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

Поддерживайте как код

Конфиг-файл — живой артефакт, а не одноразовая запись. Относитесь к нему как к остальному коду в репозитории.

• Запускайте /init для старта. Пусть инструмент сгенерирует первый черновик из вашей кодовой базы, затем доработайте вручную — сгенерированная версия лишь отправная точка, не финальный файл.
• Проверяйте, когда что-то идёт не так. Каждый раз, когда агент делает что-то нелепое, спрашивайте себя: не отсутствующая ли или вводящая в заблуждение строка в конфиге причиной?
• Регулярно чистите. Повторно применяйте тест для каждой строки ко всему файлу. Строки, которые несли нагрузку в прошлом квартале, сейчас могут быть мёртвым грузом.
• Проверяйте изменения по поведению. Не доверяйте, что правка помогла — наблюдайте, действительно ли поведение агента изменилось. Если разницы не видно, строка, скорее всего, ничего не делает.
• Добавляйте в git. Общий, версионируемый конфиг означает, что вся команда вносит вклад и пользуется результатом, а изменения видны на ревью.

Самая ценная привычка — цикл самосовершенствования: когда агент делает ошибку, добавляйте одно-единственное правило, чтобы она не повторилась. За несколько недель этот цикл сходится к конфигу, который точно отражает подводные камни именно вашего проекта — ничего лишнего.

Стартовый шаблон AGENTS.md

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

# AGENTS.md

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Test (all): `npm test`
- Test (single file): `npm test -- path/to/file.test.ts`
- Lint + autofix: `npm run lint -- --fix`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Testing
- Run `npm test` and `npm run typecheck` before every commit.
- New code needs a test in the matching `*.test.ts` file.
- Integration tests need a running DB: `npm run db:up` first.

## Project structure
- `src/api/handlers/` — HTTP route handlers
- `src/services/` — business logic (no HTTP/DB code here)
- `src/db/` — schema + queries; migrations in `src/db/migrations/`
- `web/` — React frontend (separate AGENTS.md inside)

## Code style
- 2-space indentation, single quotes, no default exports.
- Throw typed errors from `src/errors.ts`, never bare `Error`.
```ts
// Good: typed error, narrow return
export async function getUser(id: string): Promise<User> {
  const user = await db.users.find(id);
  if (!user) throw new NotFoundError('user', id);
  return user;
}

Git workflow

• Branch from main: feature/<short-desc> or fix/<short-desc>.
• Conventional Commits (feat:, fix:, chore:).
• Open a PR; never push directly to main.

Boundaries

• NEVER edit src/db/migrations/ by hand — generate with npm run db:migrate:new.
• NEVER touch dist/, node_modules/, or *.generated.ts (all generated).
• NEVER commit secrets; required env vars are documented in .env.example.

Чтобы иметь единый источник истины для всех инструментов, положите рядом однострочный `CLAUDE.md` с содержимым `@AGENTS.md` и давайте ссылки на глубокие архитектурные заметки (например, `DESIGN.md`, ваши ADR) вместо того, чтобы вставлять их в конфиг.

## Что дальше

Компактный, конкретный конфиг-файл — одно из конкретных поведений, отличающих разработчиков с AI-assisted от по-настоящему AI-native. [Узнайте свой AI-native уровень](/quiz) за три минуты — там оценивается именно такое мастерство — а когда будете готовы настроить инструментальную цепочку, начните с [рекомендованного стека ProCoders](/stack).