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

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

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

Я держу СмыслоКод на 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 - это базовая ловушка любой системы с несколькими источниками правды. Подробнее эту проблему я разбираю в гайде про мультиагентную работу.

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

Почему Claude Code не читает AGENTS.md напрямую?

Документация Claude Code по работе с памятью говорит дословно:

Почему именно так. Команда Claude Code не хочет, чтобы кросс-инструментный стандарт жил в их кодовой базе как ещё одно «магическое имя» с собственной логикой. Вместо этого они дали универсальный синтаксис @path/to/file внутри CLAUDE.md - и пусть тот файл, который импортируют, называется как угодно. AGENTS.md в этом смысле - просто партнёр по контракту, а не равноправный второй конфиг.

Это решение чище, чем «читать оба файла»:

• Не возникает конфликтов. Если оба файла существуют и говорят разное, у Claude нет правила «кто из них приоритетнее». В импортной модели приоритет всегда один: CLAUDE.md определяет порядок и может переопределить что угодно ниже импорта.
• Не нужно поддерживать parsing AGENTS.md в Claude Code. AGENTS.md - стандарт под управлением Linux Foundation, спецификация может меняться. Anthropic не привязывает себя к чужому темпу.
• Сохраняется обратная совместимость. Если завтра ты переименуешь AGENTS.md в BOT.md или SHARED.md - меняется одна строка в CLAUDE.md, не нужно ждать релиза Claude Code.

Это та же логика, что у package.json и зависимостей: вместо того, чтобы npm читал три разных лок-файла, есть один package.json с импортами. Чище и предсказуемо.

Как сделать @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 Code при первом обнаружении импорта показывает диалог: «вот эти файлы будут включены, ты согласен?» Если отказался - импорты остаются выключенными и диалог больше не показывается. Это защита от того, чтобы случайно подгрузить чужой файл в контекст.

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

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

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

ln -s AGENTS.md CLAUDE.md

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

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

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

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 - в гайде по сафе-моду.

Если у тебя репо моноплатформенный (только Mac, только Linux) и Claude-специфичных правил нет - symlink проще на одну строку. Но в 9 случаях из 10 импорт удобнее.

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

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

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

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

1. Положить всё общее в AGENTS.md - 95% правил живёт там.
2. Создать CLAUDE.md с первой строкой @AGENTS.md и блоком Claude-только правил снизу.
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 так:

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

Интерактивный режим включается через переменную среды:

CLAUDE_CODE_NEW_INIT=1 claude

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

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

Как разделить инструкции на общие и 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 в контекст не попадают. Так контекстное окно тратится только на актуальное.

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

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

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

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

У меня в СмыслоКод был 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, который логирует, какие файлы загружены - полезно для отладки многослойных схем.

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

Практикум по вайб-кодингу

+Твой второй мозг

3 вечера - стек, метод, первый проект

Старт 23–25 июня  ·  2 000 ₽

Записаться →

Новые материалы - дайджестом, без спама

Гайды выходят регулярно. Подпишись, чтобы не пропускать: пришлю подборку в Telegram или на email. Раз в неделю или каждый день - выбираешь сам.

Подписаться в Telegramили на email