Разделяйте общие и продуктовые инструкции

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

Где какой продукт ищет инструкции, стоит держать перед глазами.

Продукт · Основная проектная поверхность · Локальная детализация · Глобальная поверхность

• Codex - AGENTS.md в репозитории; Вложенные AGENTS.md или AGENTS.override.md, более близкие инструкции имеют приоритет; ~/.codex/AGENTS.md
• Claude Code - CLAUDE.md или .claude/CLAUDE.md; Дочерние CLAUDE.md загружаются по мере работы; path rules в .claude/rules/; ~/.claude/CLAUDE.md
• Cursor - .cursor/rules/*.mdc или корневой AGENTS.md; Globs в MDC и вложенные AGENTS.md; User Rules в Customize

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

Две границы здесь принципиальны. Первая - про совместимость.

Не полагайтесь на случайную совместимость. Cursor официально поддерживает AGENTS.md, Claude Code документирует CLAUDE.md, Codex документирует AGENTS.md. Если команда использует три продукта, явные адаптеры надёжнее догадки, что один файл прочитают все.

Вторая - про то, чем инструкция не является.

Инструкция - не enforcement. Она попадает в контекст и влияет на решение модели, но не гарантирует его. Запрет записи в production, обязательный security scan или формат schema должны иметь технический контроль: permission, sandbox, hook, CI или серверную авторизацию.

Разделение понятно. Теперь напишем сам instruction file - и лучший ориентир тут эксплуатационный README, а не список пожеланий.