Исторически в моей агентской среде (IWE) базовым горячим файлом инструкций является CLAUDE.md: именно там лежат правила работы, протоколы, гейты и локальная культура.
Но для сторонних агентов и сред — например Pi или Codex — нативным является AGENTS.md. Они читают его первым и игнорируют остальные файлы с инструкциями. Чтобы среда оставалась agent-agnostic, нужно обеспечить однозначное чтение правил.
Варианты развязки
Можно копировать содержимое CLAUDE.md в AGENTS.md, но это создаёт риск дрейфа и расхождения источника истины. Автоматическая синхронизация снижает этот риск, но сама становится потенциальной точкой отказа: если скрипт не сработал, агент снова получает устаревшие правила.
Мой вариант — symlink. Тогда агент фактически читает один и тот же файл под разными именами. На первый взгляд может показаться, что CLAUDE.md проигнорирован. Но если AGENTS.md — это ссылка на CLAUDE.md, то содержательно агент читает тот же самый источник. Путь другой, смысл тот же.
Недостаток подхода — сложнее выделять агент-специфичные инструкции. В моём случае они вынесены отдельно, в скрытый каталог .pi.
Ещё один практичный вариант — оставить отдельный AGENTS.md, но явно написать в нём: «перед работой прочитай CLAUDE.md». Это слабее symlink, потому что зависит от дисциплины агента, но лучше, чем молча заслонять локальный CLAUDE.md.
Иначе появляется тихий риск: Claude живёт по одним правилам, Pi — по другим, Kimi — по третьим. На уровне файлов всё выглядит нормально, но рабочая культура начинает расходиться.
Расхождение с отраслевым стандартом
Здесь отмечу честно: моё направление обратно тому, к которому пришла индустрия.
AGENTS.md — это уже оформленный открытый стандарт (его ведёт Agentic AI Foundation под Linux Foundation, нативно читают 25+ инструментов: Codex, Cursor, Copilot, Windsurf, Aider, Zed и другие; 60k+ репозиториев). Консенсус 2026 года: источником истины делают именно AGENTS.md — вендор-нейтральный файл, который все агенты читают буквально, — а CLAUDE.md оставляют тонким мостиком. Я же предлагаю обратное: CLAUDE.md как источник, AGENTS.md как ссылку на него.
Причина моего выбора прикладная: вся машинерия среды (правила, протоколы, обновление шаблона) исторически завязана на CLAUDE.md, и разворачивать канон — отдельная миграция. Грубая развилка: для одиночного Claude-репозитория CLAUDE.md-центричность удобнее; для мультиагентной или командной среды отраслевой канон — AGENTS.md.
Техническая тонкость: почему @import работает только в одну сторону
Рекомендуемый Anthropic паттерн — тонкий CLAUDE.md с первой строкой @AGENTS.md и Claude-специфика ниже. Но раскрытие @-ссылок — это фича самого Claude Code. Поэтому паттерн работает только когда источник = AGENTS.md: сторонний агент, читая AGENTS.md, видит реальное содержимое.
Развернуть в обратную сторону (AGENTS.md со ссылкой @CLAUDE.md) нельзя — Pi или Codex увидят буквальную строку @CLAUDE.md и не развернут её, то есть не-Claude агенты, ради которых всё затевалось, получат пустышку. Именно поэтому консенсус держит AGENTS.md источником. Если же нужен именно CLAUDE.md-источник — остаётся symlink: он переносит содержимое в любую сторону.
Сводка механик: symlink (ноль дрейфа, но Windows требует core.symlinks), @import (кросс-платформенно, но только AGENTS.md-источник), генерация скриптом (работает, но скрипт — отдельная точка отказа), «прочитай CLAUDE.md» текстом (слабее всех, зависит от дисциплины агента).
Чьё это решение
Направление источника истины выбирает мейнтейнер среды или шаблона — тот, кто отвечает за её архитектуру и установленную базу. Мы как пользователи под это направление адаптируемся: какой бы файл ни был назначен каноном, наша задача — не плодить второй источник, а подключиться к назначенному (ссылкой, импортом или генерацией) и держать агент-специфику отдельным слоем.
Вывод
Важен не конкретный файл-победитель, а инвариант — один смысловой источник и совместимые входы для разных агентов. CLAUDE.md и AGENTS.md не должны расходиться; кто из них канон — решает мейнтейнер, а среда остаётся цельной, пока расхождения нет.