CLAUDE.md и AGENTS.md:какой агент читает какой файл.

Что это за файлы

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

• CLAUDE.md относится только к Claude Code. Он может лежать в корне проекта (./CLAUDE.md или ./.claude/CLAUDE.md), в ~/.claude/CLAUDE.md для всех ваших проектов и в подпапках. Файл CLAUDE.local.md хранит личные заметки для одного проекта.
• AGENTS.md — открытый формат, описанный на agents.md, README для агентов. Его читают Codex, Cursor, кодовый агент GitHub Copilot, Gemini CLI, Zed и многие другие. В монорепозитории AGENTS.md в подпапке действует для этой части, и побеждает ближайший файл.

Содержимое по сути одно и то же. Различается то, какой инструмент подхватывает файл.

Что Claude Code делает с AGENTS.md

Документация Claude Code описывает три случая, для версии 2.1.277 и новее:

• Только AGENTS.md в проекте, CLAUDE.md нет: Claude Code читает AGENTS.md.
• Оба файла в проекте: Claude Code читает только файлы CLAUDE.md.
• CLAUDE.md, который импортирует AGENTS.md через @AGENTS.md: Claude читает CLAUDE.md вместе с AGENTS.md.

Именно второй случай удивляет людей. Если добавить CLAUDE.md, пусть даже крошечный, в репозиторий, где уже есть AGENTS.md, Claude перестаёт читать AGENTS.md, пока CLAUDE.md его не импортирует. То же касается CLAUDE.local.md. Старые версии Claude Code читали только CLAUDE.md, поэтому импорт по-прежнему надёжный выбор. В документации также описана настройка Project instructions в /config, чтобы Claude читал оба файла вместе.

Один набор инструкций

Выберите один файл как источник истины. Документированы два способа:

1. Импортировать AGENTS.md из CLAUDE.md

   Создайте CLAUDE.md рядом с AGENTS.md, первой строкой которого будет @AGENTS.md, а ниже добавьте инструкции только для Claude. Импорты используют синтаксис @path, относительные пути отсчитываются от файла, где они записаны, а импортируемые файлы могут импортировать другие до четырёх уровней вложенности.

2. Сделать CLAUDE.md символической ссылкой на AGENTS.md

   Выполните ln -s AGENTS.md CLAUDE.md, если вам нечего добавить специально для Claude. Документация предупреждает, что инструменты правки Claude не пишут через символическую ссылку, а в Windows закоммиченная ссылка может выгрузиться как однострочный текстовый файл, поэтому для общего репозитория импорт надёжнее.

Не используйте третий подход: CLAUDE.md, в котором словами написано «прочитай AGENTS.md». Claude увидит файл, только если решит его открыть, а импорт загружает его каждый раз.

Общий AGENTS.md

Положите в AGENTS.md то, что нужно любому агенту:

# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- TypeScript, strict mode. No default exports.
- Update the tests with every change.

## Do not
- Edit files under `generated/`.
- Commit without running the tests.

Пишите коротко и конкретно. В документации Claude Code советуют укладываться примерно в 200 строк на один CLAUDE.md, потому что длинные файлы стоят контекста и выполняются менее надёжно.

Частые ошибки

• Два файла расходятся. Одну копию обновили, другую нет. Используйте импорт.
• Добавили CLAUDE.md и потеряли AGENTS.md. См. выше: импортируйте его.
• Секреты в любом из файлов. Их коммитят, и они загружаются в каждую сессию.
• Расплывчатые правила. «Пиши чистый код» ничего не даёт. «Запусти npm test, прежде чем сказать, что закончил» даёт.
• Противоречивые правила в файле родительской папки и файле подпапки.

Чтение и ревью этих файлов

Оба — обычный Markdown, поэтому DotMD открывает CLAUDE.md и AGENTS.md как любой .md-файл, с оглавлением и историей каждого изменения, и показывает, что в них поменял агент. Чтение бесплатно. См. также Claude Code и Codex с DotMD.

Вопросы о CLAUDE.md и AGENTS.md

Другие вопросы