Как сделать один файл инструкций для Claude Code, Codex и Cursor в 2026

Каждый день в Telegram-канале - что нового в вайб-кодинге: инструменты, примеры, ошибки. Подпишись, чтобы быть в курсе.

Что меняется, когда у тебя сразу Claude Code, Codex и Cursor?

Я держу tarasovcode на Claude Code, но регулярно пробую Codex и Cursor на отдельных задачах. У меня в CLAUDE.md около 250 строк инструкций - что в каком порядке читать, что трогать нельзя, какие команды для развёртывания, какие правила оформления коммитов. Когда я первый раз попробовал Codex CLI на проекте, он не знал ни одного правила: дёргал git push --force, лез в .env, переименовывал файлы без аккуратности.

Я сначала скопировал CLAUDE.md в AGENTS.md руками. Через две недели обнаружил, что в проекте уже 4 версии одной и той же инструкции: в CLAUDE.md, AGENTS.md, .cursorrules и .windsurf/rules/. Все немного расходятся. Это не проблема Claude или Cursor - это базовая ловушка любой системы с несколькими источниками правды. Подробнее эту проблему я разбираю в гайде про мультиагентную работу.

В июне 2026 документация Anthropic по памяти Claude Code отвечала на это одним способом: общий файл плюс импорт. С сентября 2026 Claude Code читает AGENTS.md сам, если в проекте нет CLAUDE.md, и импорт нужен, когда у тебя есть правила для одного Claude. Дальше разбираю, когда хватает одного AGENTS.md, как настроить импорт и как отделить общие правила от Claude-специфичных.

Читает ли Claude Code AGENTS.md сам?

До сентября 2026 ответ был «нет». Issue #6235 с просьбой поддержать AGENTS.md провисел открытым с августа 2025 и закрылся 17 августа 2026. Документация по памяти всё это время отправляла к одному решению: заведи CLAUDE.md и подключи в нём AGENTS.md импортом. С версии 2.1.277 документация говорит другое:

Что именно прочитает Claude Code, зависит от того, какие файлы лежат в проекте:

Для этой проверки считаются CLAUDE.md, .claude/CLAUDE.md и CLAUDE.local.md в рабочей папке и в любой папке выше. Личный ~/.claude/CLAUDE.md, корпоративный managed-файл и правила из .claude/rules/ не считаются: они грузятся рядом с AGENTS.md.

Когда CLAUDE.md нет, Claude Code при старте читает все AGENTS.md и .claude/AGENTS.md в рабочей папке и выше, а AGENTS.md из подпапки подхватывает, когда открывает файл в этой подпапке. Импорты @path внутри AGENTS.md тоже работают. AGENTS.local.md, AGENTS.override.md и содержимое папки .agents/ Claude Code не читает.

Ловушка: личный CLAUDE.local.md тоже считается. Заведёшь его, чтобы держать свои незакоммиченные правила, и Claude Code молча перестанет читать AGENTS.md. Выход - настройка ниже.

Поведение меняется в /config, пункт Project instructions:

Если хочешь держать CLAUDE.local.md и не терять AGENTS.md, ставь claude-md-and-agents-md. Двойного чтения при этом не будет: AGENTS.md, который уже подключён строкой @AGENTS.md или через символьную ссылку, Claude Code второй раз не загружает, какое бы значение ни стояло.

Проверить, что файл подхватился, можно командой /memory: с версии 2.1.280 путь к AGENTS.md виден в списке. На версиях до 2.1.277 и в сессиях, где выключен встроенный плагин agents-md, Claude Code читает только CLAUDE.md, а пункта Project instructions в /config нет. До версии 2.1.281 так же вели себя сессии через Amazon Bedrock и с выключенной телеметрией. В первой сессии после обновления со старой версии AGENTS.md тоже может не подхватиться, со следующей всё работает.

Что из этого следует для схемы с одним файлом. Если правил только для Claude у тебя нет, CLAUDE.md можно не заводить: хватит AGENTS.md, его прочитают Claude Code, Codex и Cursor. Если такие правила есть (плановый режим для опасных папок, навыки, хуки), нужен CLAUDE.md, а с ним Claude Code перестаёт читать AGENTS.md сам. Тогда AGENTS.md подключают внутрь CLAUDE.md строкой @AGENTS.md, и эта схема работает так же, как до сентября. Она же выручает на старых версиях Claude Code. Дальше разбираю её подробно.

Как сделать @AGENTS.md импорт внутри CLAUDE.md?

Минимальный рабочий пример из официальной документации:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Что здесь происходит. Первая строка @AGENTS.md - это директива импорта. Когда Claude Code разбирает CLAUDE.md в начале сессии, он находит этот импорт и подставляет содержимое AGENTS.md целиком на это место. Дальше идёт заголовок ## Claude Code - просто markdown, но он действует как раздел «дополнения для Claude». Под ним - правило, которое касается только Claude Code: использовать плановый режим для изменений в папке биллинга. Codex CLI или Cursor этот файл вообще не открывает, для них живёт чистый AGENTS.md.

Цитата из документации про работу импортов:

Несколько практических нюансов:

• Относительные и абсолютные пути. @AGENTS.md - относительно файла, в котором написан импорт. @/Users/me/shared/rules.md или @~/.claude/personal.md - абсолютные. Я использую @~/.claude/personal.md для личных привычек, которые не хочу класть в репо.
• Глубина 4 hop'а. AGENTS.md внутри себя может импортировать @docs/coding-style.md, а coding-style.md - дальше что-то ещё, и так до 4 уровней. Этого достаточно для любой реальной структуры.
• Backtick'и блокируют импорт. Если в тексте написано `@README` - это просто упоминание имени, а не импорт. Это удобно, когда нужно объяснить читателю, как работает импорт, не запуская его.
• Аппрув для файлов снаружи проекта. Если импорт ведёт за пределы рабочей папки, как @~/.claude/personal.md, Claude Code при первой встрече показывает диалог со списком таких файлов. Если отказался - внешние импорты остаются выключенными и диалог больше не показывается. @AGENTS.md из корня проекта диалога не вызывает. Это защита от того, чтобы случайно подгрузить чужой файл в контекст.

После того, как я перешёл на эту схему в tarasovcode, мой CLAUDE.md уменьшился с 250 строк до 60: @AGENTS.md + пять-семь правил, которые касаются только Claude Code (плановый режим для опасных папок, что не трогать в админке, как формулировать коммиты). Всё общее живёт в AGENTS.md, который читают Codex и Cursor.

Когда выбрать symlink, а когда импорт?

Документация показывает symlink-вариант так:

ln -s AGENTS.md CLAUDE.md

И сразу честно предупреждает про Windows:

Сравнительная таблица:

Я в tarasovcode использую импорт. Причины:

1. Команда смешанная. Я на Mac, у нас в практикуме участники на Windows и Mac примерно поровну. Если в репо появится symlink - у Windows-юзеров без Developer Mode он развернётся в обычный текстовый файл с одной строкой AGENTS.md внутри. Это вызывает странные баги: то правила работают, то нет, и непонятно почему.
2. Я хочу Claude-only правила. В моём CLAUDE.md под @AGENTS.md живёт блок «Claude Code» с правилами: использовать --effort high для архитектурных задач, проверять npm run build перед git push, не дёргать /api/v1/deploy руками. Codex эти команды не понимает.
3. Лучше для отладки. Когда что-то идёт не так, я открываю CLAUDE.md и вижу: вот импорт, вот мои оверрайды. У symlink нет такого «вот тут добавлено». Подробнее про отладку настроек Claude Code - в гайде по сафе-моду.

Если Claude-специфичных правил нет, с версии 2.1.277 symlink уже не нужен: удали CLAUDE.md, и Claude Code прочитает AGENTS.md сам. Оставь symlink, только если кто-то в команде сидит на версии старше 2.1.277 и не может обновиться. Если правила для Claude есть, в 9 случаях из 10 импорт удобнее.

Что читают Codex, Cursor, Copilot, Windsurf и Gemini CLI?

Карта по 7 главным инструментам (на основе официальной документации каждого и публикации deployhq.com 2026):

Что из этого следует. Если в репо живёт AGENTS.md (плюс CLAUDE.md с импортом, когда нужны правила для Claude) - 5 из 7 инструментов получают свежие инструкции автоматически. Cursor и Windsurf, у которых свои нативные файлы, можно либо оставить как есть (AGENTS.md они тоже читают), либо положить туда @AGENTS.md импорт - но синтаксис у них отличается, не всегда поддерживается.

Самая простая стратегия для нового проекта:

1. Положить всё общее в AGENTS.md - 95% правил живёт там.
2. Создать CLAUDE.md, если нужны правила только для Claude: первой строкой @AGENTS.md, блок Claude-только правил снизу. Нет таких правил - CLAUDE.md не нужен, Claude Code с версии 2.1.277 прочитает AGENTS.md сам.
3. На Cursor оставить .cursor/rules/ для редких case'ов когда нужно что-то Cursor-специфичное (его команды @Codebase, @Docs).
4. На Windsurf - то же самое: старый .windsurfrules забыть, новый .windsurf/rules/ использовать только если нужны паттерны под их синтаксис.

Этот подход даёт 80% выигрыша при 20% работы. В моём опыте, когда я разруливал смешанные команды в Антигравити, держать больше двух источников правды (общий + Claude-only) - это уже больно. Если в команде кто-то добавит правило в .cursorrules и забудет в AGENTS.md - через неделю Cursor и Codex будут спорить друг с другом.

Как /init в Claude Code подхватывает существующий AGENTS.md?

Anthropic в документации описывает поведение /init так:

Что это даёт на практике. У меня в репо tarasovcode был .cursorrules от тех времён, когда я пробовал Cursor (около 80 строк), и AGENTS.md (120 строк, собран вручную). Когда я запустил claude /init, команда взяла оба файла, дедуплицировала похожие правила и собрала чистый CLAUDE.md за минуту. Я потом проверил и слегка отредактировал - убрал устаревшие пункты, добавил структуру через заголовки. Это было быстрее, чем переписывать с нуля.

Интерактивный режим, в котором /init читает и AGENTS.md, включается через переменную среды:

CLAUDE_CODE_NEW_INIT=1 claude

После запуска /init Claude задаёт серию уточняющих вопросов: какие артефакты настроить (CLAUDE.md, skills, hooks), какой стек у проекта, какие команды для тестов. Затем субагент исследует кодбейз - читает package.json, README.md, файлы конфигурации - и заполняет недостающие части. В конце показывает proposal, который ты можешь отредактировать перед сохранением. Подробнее про настройку Claude Code на старте проекта - в отдельном гайде.

Теперь про обратную сторону. Если в проекте уже есть живой AGENTS.md, после /init рядом появится CLAUDE.md с копией его правил. С этого момента Claude Code по умолчанию читает только CLAUDE.md, и источников правды снова два: поправишь AGENTS.md, а Claude продолжит работать по старой копии. Команда /import делает похожее: дописывает в CLAUDE.md разовую копию AGENTS.md. Чтобы источник остался один, после /init поставь первой строкой CLAUDE.md импорт @AGENTS.md и убери из CLAUDE.md всё, что повторяет AGENTS.md.

Команда /init - правильная точка входа для нового проекта или для проекта, в который ты переезжаешь с Cursor или Copilot. Не нужно искать «лучший шаблон CLAUDE.md в интернете» - Anthropic уже учитывает то, что лежит в репо. Если же в проекте есть живой AGENTS.md и правил только для Claude нет, /init не нужен: Claude Code прочитает AGENTS.md сам.

Как разделить инструкции на общие и Claude-специфичные?

Я разделяю по такому принципу. Общие правила, которые идут в AGENTS.md:

• Что не трогать в коде. Папки .env, node_modules, prisma/migrations (только через prisma migrate), .next/, .git/.
• Как именовать. Ветки feat/, fix/, chore/. Коммиты - префиксы feat:, fix:, docs: плюс короткое описание. Файлы компонентов в kebab-case.
• Команды для тестов/линта. npm run build, npm run lint, npm test. Какую команду гнать перед git push.
• Архитектурные принципы. Что лежит в src/lib/, что в src/components/, где живёт бизнес-логика, где UI.
• Безопасность. Никогда не коммитить секреты. Запрос к продовой БД - только через prod-psql. Запрос к проду через SSH - только через алиас prod, не через root@IP.

Claude-специфичные правила, которые идут в CLAUDE.md (под @AGENTS.md):

• Плановый режим. Использовать plan mode для изменений в опасных папках (например, src/billing/).
• Уровень усилия. Для архитектурных задач - --effort high, для рутины - medium.
• Навыки и скиллы. Какие ИИ-агенты и навыки запускать в каких ситуациях. Например: «при работе с гайдом запусти skill build-masterskaya-guide».
• Память Claude. Что класть в auto memory, а что - в CLAUDE.local.md. Подробнее про память Claude - в гайде про Memory и CLAUDE.md.
• Хуки. Если в .claude/settings.json настроены хуки, описать в CLAUDE.md зачем они нужны (Codex и Cursor про них не знают, и им это не нужно).
• Скиллы и команды. Список slash-команд, которые часто использую (/init, /cd, /memory, /plan).

Граница не всегда чистая. Например, правило «никогда не делать git push --force в main» - это явно общее, оно в AGENTS.md. А правило «при git push в hot-branch использовать plan mode сначала» - это уже про Claude Code, оно в CLAUDE.md. Тест: «если завтра я уберу Claude Code и оставлю только Codex - это правило ещё актуально?». Да - в AGENTS.md. Нет - в CLAUDE.md.

Что положить в AGENTS.md, а что в CLAUDE.md или .claude/rules?

Если правила больше 200 строк - пора резать. Anthropic в документации советует целиться в 200 строк на файл, потому что длинные CLAUDE.md начинают молча терять адгезию: Claude вроде читает, но реже следует.

Структура для большого проекта, которая работает у меня:

my-project/
├── AGENTS.md                    # 100-150 строк, общее
├── CLAUDE.md                    # 30-50 строк: @AGENTS.md + Claude-only
└── .claude/
    ├── CLAUDE.md                # альтернатива корневому, тот же файл
    └── rules/
        ├── api.md               # с paths: ['src/api/**']
        ├── components.md        # с paths: ['src/components/**']
        ├── testing.md           # без paths, всегда активно
        └── security.md          # без paths, всегда активно

Каждый файл в .claude/rules/ может иметь frontmatter:

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Каждый endpoint проверяет вход через zod
- Ошибки в стандартном формате `{error, code}`
- OpenAPI-комменты обязательны

Эти правила Claude подгружает только когда работает с файлами по этому шаблону. Если он трогает src/components/Button.tsx - правила API в контекст не попадают. Так контекстное окно тратится только на актуальное. Папка .claude/rules/ работает и без CLAUDE.md: если в проекте лежит только AGENTS.md, правила из неё грузятся рядом с ним и прямое чтение AGENTS.md не выключают.

Cursor и Windsurf поддерживают такой же подход через свои папки .cursor/rules/ и .windsurf/rules/. AGENTS.md как стандарт умеет ссылаться на эти папки, но синтаксис кросс-инструментный пока не до конца стабильный. Безопаснее держать общие правила в AGENTS.md, а path-scoped - дублировать в .claude/rules/ и .cursor/rules/ (это редкие специфичные кейсы, не основная масса правил).

Полезные расположения CLAUDE.md (по приоритету, от широкого к узкому):

Я держу ~/.claude/CLAUDE.md с тремя строками: «всегда отвечай по-русски», «никогда не дёргай Stripe в примерах (мы на YooKassa)», «бренд tarasovcode пишется слитно». Эти правила живут на все мои проекты, не нужно дублировать в каждом репо.

Из этих четырёх уровней прямое чтение AGENTS.md выключают только проектный CLAUDE.md и CLAUDE.local.md. Личный ~/.claude/CLAUDE.md и managed policy ему не мешают, Claude Code читает их рядом с AGENTS.md.

Что делать, если AGENTS.md уже устарел в твоём проекте?

У меня в tarasovcode был AGENTS.md от мая 2025 - 180 строк, многие пункты устарели (упоминал Anthropic API endpoints, которые с тех пор изменились; примеры с claude --tools синтаксисом, которого больше нет; правила про ~/.claude/projects/ с устаревшей структурой).

План, который я применил для актуализации:

1. Прогнать через claude в плановом режиме. Открываю репо, запускаю claude --safe-mode, прошу: «Перечитай AGENTS.md и предложи список пунктов, которые устарели или повторяются. Не правь, только список». За 2 минуты получил список из 23 пунктов на ревью.
2. Удалить очевидно мёртвое. Из 23 пунктов 9 были однозначно устаревшие - синтаксис команд, endpoints, имена флагов. Удалил эти строки.
3. Объединить дубли. Ещё 6 пунктов повторяли друг друга в разных формулировках («не пушь форсом», «никогда --force», «избегай git push -f»). Свёл в одну строку.
4. Добавить новое. Что я заметил, что Claude/Codex регулярно делает не так за последний месяц - дописал по правилу «одна строка на один паттерн ошибки». Получилось 8 новых пунктов.
5. Прогнать через subagent для финальной проверки. Запросил у Claude review с указанием «найди противоречия, неоднозначности, дубли». Нашёл 3 формулировки которые можно было сделать чётче. Поправил.

Через час AGENTS.md весил 110 строк, был свежим, и я знал каждую строку лично. Под него легко собирался CLAUDE.md на 30 строк. Codex после этого стал заметно аккуратнее на тестах - я подозреваю, что часть его «странных» решений как раз шла от устаревших инструкций, которые он добросовестно выполнял.

Главный принцип для живого AGENTS.md:

• Каждое правило - ответ на повторяющуюся ошибку. Если за месяц я ни разу не вспоминал это правило - его нет смысла держать.
• Правила пишутся в форме команд, не теории. «Использовать 2 пробела» - правило. «Стиль кода должен быть аккуратным» - не правило.
• Конкретика побеждает обобщения. «Запускай npm run build перед git push» - правило. «Тестируй изменения» - не правило.

Что точно НЕ работает в этой схеме?

Несколько вещей, которые я узнал на грабли за полгода работы с этой схемой:

1. Cursor autocomplete не использует AGENTS.md. Когда Cursor предлагает дополнение строки в редакторе, он не читает AGENTS.md в реальном времени - там работает отдельный быстрый движок. Правила из AGENTS.md влияют только когда ты делаешь chat-запрос внутри Cursor. Это значит: писать в AGENTS.md «не используй var, используй const» - оно не подействует на автокомплит, нужно настраивать через ESLint или TypeScript-конфиг.

2. Хуки Claude Code в AGENTS.md не работают для Codex. Если в .claude/settings.json настроен PreToolUse хук, который блокирует определённое действие - это знание полезно только Claude. Codex не знает про хуки, для него это «инструмент сам решает». В AGENTS.md имеет смысл написать «не делай X», в CLAUDE.md под импортом - «есть хук, который блокирует X физически».

3. Copilot и .github/copilot-instructions.md. GitHub Copilot читает свой файл и пока не очень читает AGENTS.md. Если в команде активный Copilot - либо положить отдельный .github/copilot-instructions.md с урезанной версией правил, либо использовать Copilot Extensions которые знают про AGENTS.md. Это сейчас активно меняется, через 3-6 месяцев картина другая.

4. Symlink не отслеживается git как изменение CLAUDE.md. Если ты сделал ln -s AGENTS.md CLAUDE.md и через неделю обновил AGENTS.md - git покажет diff только по AGENTS.md. Это нормально, но коллега, который ревьюит PR, может не понять, что и CLAUDE.md тоже обновился (через символьную ссылку). Решение: в описании PR явно писать «обновил AGENTS.md, через симлинк это же видит Claude Code».

5. Глубокие импорты тяжелы для отладки. Если AGENTS.md импортирует @docs/coding-style.md, который импортирует @docs/typescript.md - и где-то правило конфликтует с другим, дебажить сложно. Я держу импорты на одном уровне (CLAUDE.md → AGENTS.md, дальше не углубляюсь). Anthropic даёт хук InstructionsLoaded, который логирует, какие файлы загружены - полезно для отладки многослойных схем. Учти: на AGENTS.md, подключённый через импорт или symlink, хук срабатывает, а на AGENTS.md, который Claude Code прочитал сам, нет.

Полная схема по вайб-кодингу за вечер: ИИ-клон + Второй мозг + контекст-инжиниринг. 3 эфира, 2000 ₽. Записи остаются у тебя.