---
title: "Что писать в AGENTS.md и CLAUDE.md?"
seoTitle: "AGENTS.md и CLAUDE.md: что действительно помогает агентам"
navTitle: "AGENTS.md и CLAUDE.md"
description: "Что писать в AGENTS.md и CLAUDE.md по данным бенчмарков агентов: полезные команды, рабочие ограничения, дорогие ловушки и что лучше не включать."
slug: agents-md-claude-md-best-practices
lang: ru
date: 2026-08-06
updated: 2026-08-06
author: "Chatcode"
category: guide
faq:
  - q: "Делают ли AGENTS.md и CLAUDE.md агентов для программирования точнее?"
    a: "По текущим исследованиям — не стабильно. Недавние работы показывают неоднозначное влияние на эффективность и почти никакого общего роста правильности решений. Тем не менее конкретные рабочие инструкции могут сократить лишние команды, время и токены."
  - q: "Может ли Claude Code использовать существующий файл AGENTS.md?"
    a: "По умолчанию Claude Code не загружает AGENTS.md напрямую. Добавьте `@AGENTS.md` в небольшой файл CLAUDE.md, чтобы импортировать общие инструкции, а ниже допишите только то, что действительно относится к Claude."
  - q: "Какой длины должен быть файл AGENTS.md или CLAUDE.md?"
    a: "Держите корневой файл настолько коротким, насколько позволяет репозиторий. Сейчас Anthropic рекомендует менее 200 строк на один CLAUDE.md. У Codex по умолчанию действует лимит 32 KiB на всю цепочку инструкций, но это потолок, а не ориентир для объёма."
---

Файл инструкций в репозитории легко превращается в сжатый README, эссе об
архитектуре и перечень достойных инженерных принципов. Агент получает всё это в
каждой задаче — даже когда бо́льшая часть к ней не относится.

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

## Короткий ответ

Вносите факт в корневой файл инструкций, если выполняются все три условия:

1. Он касается большей части работы в зоне действия файла.
2. Агент не может быстро и надёжно выяснить его из репозитория.
3. Следование ему меняет конкретное действие или проверку.

Хорошие примеры:

- `pnpm test --filter api` — быстрая команда тестов для изменений в API.
- Полный набор интеграционных тестов идёт 25 минут, и запускать его нужно один
  раз, после того как прошли целевые тесты.
- Файлы в `generated/` нужно менять через `pnpm generate`.
- Добавление продакшен-зависимости или изменение миграции базы данных требует
  подтверждения.
- Изменение не готово, пока не прошли проверка типов и соответствующий точечный
  тест.

Не включайте общие пожелания вроде «пиши чистый код», скопированные списки
пакетов и описания, которые агент получит, прочитав манифест и дерево
исходников. Для разовых требований используйте промпт задачи, для процедуры по
запросу — навык (skill), а для правил, которые должны соблюдаться механически, —
тесты, хуки или CI.

## AGENTS.md и CLAUDE.md похожи, но не одинаковы

Оба файла дают постоянные инструкции для репозитория, но правила их поиска и
область действия определяет агент, который их читает.

| | Codex `AGENTS.md` | Claude Code `CLAUDE.md` |
| --- | --- | --- |
| Корневой файл проекта | `AGENTS.md` | `CLAUDE.md` или `.claude/CLAUDE.md` |
| Личные настройки по умолчанию | `~/.codex/AGENTS.md` | `~/.claude/CLAUDE.md` |
| Более точечные инструкции | Вложенный `AGENTS.md` или `AGENTS.override.md` | Вложенный `CLAUDE.md` или правила с привязкой к путям в `.claude/rules/` |
| Как объединяются файлы | Цепочка от корня до рабочей директории; более близкие файлы применяются позже | Родительские файлы загружаются при запуске, вложенные — когда Claude работает в этом поддереве |
| Текущие рекомендации по размеру | Лимит по умолчанию — 32 KiB на все найденные файлы вместе | Anthropic рекомендует менее 200 строк на файл |

Codex собирает цепочку инструкций один раз за запуск или за сессию TUI. Он
проверяет глобальные инструкции, а затем проходит от корня проекта до текущей
рабочей директории. Более близкий файл попадает в объединённый промпт позже и
поэтому переопределяет более общие инструкции. Точный порядок поиска и правила
переопределения описаны в [документации Codex по
AGENTS.md](https://learn.chatgpt.com/docs/agent-configuration/agents-md).

Claude Code воспринимает `CLAUDE.md` как контекст, а не как обязательную к
исполнению конфигурацию. Его документация советует писать конкретные и
лаконичные инструкции и объясняет, что инструкции из больших или противоречивых
файлов соблюдаются хуже. См. раздел [How Claude remembers your
project](https://code.claude.com/docs/en/memory) («Как Claude запоминает ваш
проект»).

Если команда использует обоих агентов, храните общие инструкции в `AGENTS.md` и
импортируйте их из небольшого `CLAUDE.md`:

```md
@AGENTS.md

## Claude Code only

- Use the path-scoped rule in `.claude/rules/frontend.md` for UI changes.
```

Anthropic прямо описывает такой импорт в документации. Символическая ссылка тоже
может сработать, но импорт оставляет место для небольшого числа инструкций
специально для Claude и лучше переносится на Windows.

## Что проверяло последнее исследование с двумя агентами

Авторы препринта [Do Context Files Help Coding
Agents?](https://arxiv.org/abs/2607.27250), вышедшего в июле 2026 г., превратили
принятые пул-реквесты из трёх Python-репозиториев — PDM, firebase-admin-python и
opshin — в 17 задач на написание кода. Промптом служило описание PR, а тесты,
добавленные в реальном PR, оставались скрытыми и использовались для оценки
реализации агента.

Claude Code и Codex работали в трёх условиях:

- **без контекста (none):** файла контекста репозитория нет;
- **всегда в контексте (always on):** полный `AGENTS.md` вставлялся в каждый ход
  диалога;
- **выборочно (selective):** агент получал подсказку и при необходимости мог
  читать вики-файлы, разбитые по темам.

После трёх повторов пригодные для оценки правильности результаты дали 288
запусков:

| Стратегия | Claude Code | Codex |
| --- | ---: | ---: |
| Без контекста | 53,3% | 58,8% |
| Всегда в контексте | 55,6% | 56,9% |
| Выборочно | 55,6% | 52,9% |

Различия не были статистически значимыми. При ручном разборе авторы увидели, что
почти удавшиеся попытки проваливались из-за проектирования функциональности,
выбора паттерна или неправильного связывания компонентов, а не из-за отсутствия
какого-то факта о репозитории, который был в реальном `AGENTS.md`. Добавление
или реорганизация этого контекста не превращали такие провалы в успехи.

Этот результат не доказывает, что файлы инструкций никогда не повышают
правильность. В выборке всего три Python-репозитория и 15–17 задач на агента. По
оценке статистической мощности в статье, чтобы обнаружить эффект в 10 процентных
пунктов, понадобилось бы примерно 120–200 задач. Кроме того, проверялось более
сильное, искусственное внедрение контекста, а не просто файл на его обычном
месте в рабочем пространстве: Claude получал дополнение к системному промпту, а
Codex — текст, добавленный в начало пользовательского промпта.

У выборочного условия есть ещё одно ограничение. Его вики совпадала с исходным
`AGENTS.md` только для opshin; два других репозитория получили более обширные
сгенерированные вики, примерно в 10 и 18 раз длиннее. Поэтому выборочная
загрузка — не чистое сравнение одного и того же содержимого, доставленного
разными способами.

## Полезный результат оказался практическим

В `AGENTS.md` проекта opshin сказано, что полный набор тестов идёт больше 20
минут. Без этого предупреждения Claude запускал весь набор в среднем 3,67 раза
на ячейку эксперимента. С постоянным контекстом — 2,44 раза, с выборочным —
1,67. Среднее время работы сократилось с 2689 секунд до 2066 и 2032 секунд
соответственно, то есть примерно на 24%, причём правильность не выросла.

Это хороший аргумент в пользу конкретного типа инструкций: сообщите агенту, во
что обходится действие, и дайте ему более дешёвый правильный путь. Но это не
общее доказательство того, что работа ускоряется. Анализ был разведочным,
касался Claude на одном репозитории и при пяти задачах не имел достаточной
статистической мощности. Длительность работы Codex не изменилась, а результаты
на другом репозитории слегка сдвинулись в обратную сторону.

Осторожный вывод такой:

> Файл инструкций в репозитории может улучшить то, как агент работает, даже если
> не расширяет круг задач, которые агент способен решить.

## Более широкие данные неоднозначны

Два более ранних исследования 2026 года пришли к разным выводам об
эффективности:

- [On the Impact of AGENTS.md Files](https://arxiv.org/abs/2601.20404) охватило
  10 репозиториев и 124 пул-реквеста. Наличие `AGENTS.md` было связано с
  уменьшением медианного времени работы на 28,64% и сокращением выходных токенов
  на 16,58% при сопоставимых показателях выполнения задач.
- [Evaluating AGENTS.md](https://arxiv.org/abs/2602.11988) проверило
  сгенерированные и написанные разработчиками файлы на разных агентах и моделях.
  Общего роста успешности решения задач не обнаружилось, а стоимость инференса в
  среднем выросла более чем на 20%, хотя нестандартным инструкциям агенты
  действительно следовали.

Новая работа с двумя агентами предполагает, что противоречие могут объяснять
разные способы внедрения контекста и сложность задач, зависящая от агента. Это
гипотеза, а не окончательное примирение результатов. По совокупности трёх работ
самая обоснованная практика — оценивать файл по тому, какое поведение он меняет,
а не исходить из того, что больше контекста — значит лучше.

## Что стоит включить в полезный файл контекста

### Точные команды и быстрый путь

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

```md
## Verification

- API change: run `pnpm test --filter api` first.
- Type check: run `pnpm typecheck` after changing TypeScript.
- Full suite: `pnpm test`; takes about 18 minutes, so run it once after focused tests pass.
```

«Запусти тесты» мало что даёт. Правильная команда, её стоимость и порядок
запуска избавляют от догадок.

### Границы с причиной или безопасной альтернативой

Опишите неочевидные области, которые агент не должен изменять напрямую:

```md
## Boundaries

- Do not edit `src/generated/`; change the schema and run `pnpm generate`.
- Ask before adding a production dependency.
- Do not rewrite an existing migration; add a new migration instead.
```

Безопасный путь полезнее, чем просто запрет.

### Инварианты конкретного репозитория

Включайте соглашения, которые важны, неожиданны и не проверяются автоматически.
Например, необычное правило сопоставления ошибок, требование совместимости,
которое не покрыто тестами, или единственный сервис, для которого нужна другая
команда.

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

### Повторяющиеся ошибки, а не гипотетические

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

## Что не стоит включать

- **Шаблонные роли:** «Ты — senior-инженер» в этих исследованиях напрямую не
  оценивалось, но такая фраза не даёт ни проверяемого действия, ни факта о
  репозитории.
- **Расплывчатые идеалы:** «Следуй SOLID» или «пиши чистый код» оставляют агенту
  выводить то же проектное решение, которое он и так собирался принять.
- **Второй README:** описывайте только ту структуру, которая неожиданна или
  влияет на то, куда должно попасть изменение.
- **Полные списки зависимостей:** манифест актуальнее, и агенту его проще
  изучить.
- **Требования разовых задач:** держите их в промпте задачи, чтобы они не влияли
  на посторонние сессии.
- **Правила, которые могут обеспечить инструменты:** для детерминированных
  требований форматтеры, проверки типов, тесты, хуки и CI надёжнее текста.
- **Секреты и личные учётные данные:** файл инструкций — обычный контекст
  проекта, а не хранилище секретов.

## Компактный шаблон для старта

```md
# Repository instructions

## Fast path

- Install: `pnpm install --frozen-lockfile`
- Focused tests: `pnpm test --filter <changed-package>`
- Full suite: `pnpm test` (about 20 minutes; run after focused tests pass)

## Verification

- Run `pnpm typecheck` after TypeScript changes.
- Add or update a focused test when behavior changes.

## Boundaries

- Do not edit `generated/`; run `pnpm generate` from the schema.
- Ask before adding production dependencies or changing migrations.

## Known traps

- Tests under `integration/` require the local database started with `pnpm db:up`.
- Package-specific instructions live in that package's nested `AGENTS.md`.
```

Замените каждый пример фактом из реального репозитория. Точный файл из десяти
строк лучше подробного шаблона, заполненного общими значениями по умолчанию.

## Выбирайте минимальный надёжный механизм

| Информация | Где ей место |
| --- | --- |
| Касается большинства задач в репозитории | Корневой `AGENTS.md` или `CLAUDE.md` |
| Касается только одного поддерева | Вложенный файл инструкций или правило с привязкой к путям |
| Личные предпочтения для всех репозиториев | Файл инструкций на уровне пользователя |
| Многошаговая процедура, нужная для определённых задач | Навык, загружаемый по запросу |
| Требование только для этой задачи | Промпт задачи |
| Правило, которое должно выполняться всегда | Тест, форматтер, хук, политика или CI |

Об установке и сопровождении процедур, загружаемых по запросу, сразу для
нескольких агентов читайте в [практическом руководстве по
skills.sh](/articles/skills-sh-install-skills-ai-coding-agents). Файл инструкций
не должен подменять собой все остальные механизмы управления.

## Проверьте файл в своём репозитории

Средние значения из исследований не скажут, помогает ли конкретная инструкция
вашей кодовой базе. Выберите воспроизводимую задачу, в которой инструкция должна
менять поведение, и проведите несколько прогонов с ней и без неё на одном и том
же агенте и одной версии модели. Отслеживайте:

- результаты скрытых или независимо написанных тестов;
- запуски целевых тестов и полного набора;
- затраченное время и расход токенов;
- лишние изменения файлов и запросы разрешений;
- следовал ли агент конкретному правилу.

Оставляйте инструкцию, если она улучшает результат или предотвращает измеримые
потери. Перепишите или удалите её, если агент её игнорирует, если она
дублируется, устарела или просто удлиняет промпт. Цель — не идеальный файл
контекста, а небольшой набор фактов о репозитории, который стабильно меняет
работу к лучшему.
