Сессия с агентом начинается с чистого контекста. Он не знает, что тесты у вас гоняются через make test, а не npm test, что миграции лежат в отдельной папке и что в legacy/ лезть запрещено. Пока вы это объясняете, уходит десять минут; на следующий день всё повторяется.

Файл с правилами закрывает вопрос один раз: агент читает его в начале каждой сессии и работает по вашим договорённостям. Разберём, какой формат понимают популярные инструменты, что писать внутрь и почему часть правил всё равно не срабатывает.

AGENTS.md: общий формат

AGENTS.md — открытый формат, который авторы описывают как «README для агентов»: предсказуемое место, где лежит контекст для AI-инструментов. Формат вырос из совместной работы команд OpenAI Codex, Amp, Jules, Cursor и Factory, а сейчас его ведёт Agentic AI Foundation под эгидой Linux Foundation. По поиску GitHub файл лежит больше чем в 60 000 открытых репозиториев.

Внутри обычный markdown без обязательной схемы. Типовые разделы, которые чаще всего встречаются:

  • обзор проекта: что это, из каких частей состоит;
  • команды сборки и запуска;
  • как гонять тесты и что должно быть зелёным перед коммитом;
  • соглашения по коду и именованию;
  • требования безопасности и границы: чего трогать нельзя.

В монорепозитории файлы можно вкладывать: агент читает ближайший вверх по дереву, и он же имеет приоритет. Корневой AGENTS.md описывает общие правила, а packages/api/AGENTS.md уточняет их для конкретного пакета.

Кто что читает

Единого файла на все инструменты пока нет, поэтому важно знать особенности каждого.

Claude Code читает CLAUDE.md и AGENTS.md не видит. Если в репозитории уже есть AGENTS.md, рядом кладут CLAUDE.md со строкой-импортом @AGENTS.md, ниже дописывают пункты специально для Claude Code. Работает и симлинк, если добавлять нечего. Файлы собираются по иерархии: политика организации, затем ~/.claude/CLAUDE.md, затем ./CLAUDE.md проекта, затем файлы в подпапках — они подгружаются, когда агент читает код в этих подпапках. Тематические правила выносятся в .claude/rules/*.md, где во фронтматтере можно указать paths с глобами, и такое правило попадёт в контекст только при работе с подходящими файлами. Документация советует держать основной файл в пределах 200 строк.

Cursor хранит правила в .cursor/rules как файлы .mdc под контролем версий. Во фронтматтере три поля: alwaysApply, description и globs. Их сочетание задаёт один из четырёх режимов: правило применяется всегда, подключается по смыслу описания, цепляется к файлам по маске или вызывается вручную упоминанием через @. Вложенные AGENTS.md Cursor тоже понимает и складывает их с родительскими, отдавая приоритет более конкретным. Рекомендация из документации — не раздувать правило больше 500 строк и резать его на составные части.

GitHub Copilot различает три уровня. Файл .github/copilot-instructions.md действует на весь репозиторий. Файлы .github/instructions/*.instructions.md с полем applyTo во фронтматтере привязываются к путям. Плюс Copilot читает AGENTS.md, CLAUDE.md и GEMINI.md из любой папки, отдавая приоритет ближайшему по дереву. Все подходящие наборы инструкций отдаются модели вместе, поэтому противоречия между ними ничего не «перебивают», а просто путают.

Windsurf держит правила в .windsurf/rules (в свежих сборках Cascade — в .devin/rules), а старый .windsurfrules в корне поддерживает как легаси. Режим активации задаётся полем trigger: always_on, model_decision, glob или manual. Здесь же самые жёсткие лимиты: 12 000 символов на файл правил рабочей области и 6 000 на глобальные правила. AGENTS.md обрабатывается тем же движком.

Практический вывод: пишите содержимое один раз в AGENTS.md, а для Claude Code добавляйте однострочный CLAUDE.md с импортом. Копипаста одного и того же текста в четыре файла живёт ровно до первого изменения. Какой инструмент под какие задачи брать, разбирали в сравнении Cursor, Claude Code и Windsurf.

Что писать внутрь

Полезное правило — то, которое агент не выведет из кода сам. Проверка простая: если ответ виден из package.json, структуры папок или соседнего файла, в правилах ему делать нечего.

Что стоит записать:

  • Команды. Как поднять окружение, чем гонять тесты и линтер, что запускать перед коммитом. Особенно если команды нестандартные.
  • Договорённости. Ветки и формат коммитов, куда класть новый модуль, какие библиотеки в проекте под запретом и почему.
  • Границы. Сгенерированные файлы, вендорные папки, миграции, боевые конфиги — что агент не должен трогать без спроса.
  • Грабли. Знание, которое стоило команде дня отладки: почему тесты падают без локального Redis, почему в этом сервисе нельзя обновлять драйвер, какой порядок деплоя обязателен.
  • Стиль с примерами. Не «пиши идиоматично», а короткий пример «так принято» и «так у нас не пишут».

Что писать не стоит: пересказ README, дерево каталогов, список зависимостей, лозунги вроде «код должен быть чистым и поддерживаемым». Всё это либо выводится из репозитория, либо не поддаётся проверке. Секретам, токенам и внутренним адресам в файле правил тоже не место — он лежит в гите и уходит в контекст модели.

Формулируйте так, чтобы выполнение можно было проверить глазами. «Использовать отступ в два пробела» работает, «форматируй код правильно» — нет. «Запускать npm test перед коммитом» работает, «тестируй изменения» — нет.

Порядок загрузки и конфликты

Правила приходят из нескольких мест сразу: политика организации, настройки пользователя, файл проекта, файл в подпапке. Инструменты складывают все найденные файлы в один контекст, поэтому два пункта, требующие противоположного, остаются там оба. Дальше агент выбирает один из них, и предсказать выбор нельзя.

Отсюда простое требование к гигиене: раз в пару месяцев перечитывайте свои файлы правил целиком и выкидывайте устаревшее. Строка «пока используем Vue 2» переживает миграцию на третью версию и продолжает вредить полгода. В монорепозитории добавляется вторая беда — чужие файлы правил из соседних папок, которые к вашей задаче отношения не имеют; у Claude Code для этого есть настройка исключений, у Cursor и Windsurf помогает более узкая привязка к путям.

Правила не гарантируют поведение

Файл правил — это контекст, а не конфигурация с принудительным исполнением. Документация Claude Code говорит об этом прямо: инструкции влияют на поведение, но соблюдение не гарантировано, и для жёсткого запрета нужен хук PreToolUse или запрет на уровне настроек. Логика та же у остальных инструментов.

Поэтому критичные вещи держите на технических рубежах:

  • запрет на изменение файла — правами доступа или хуком;
  • формат кода — линтером и форматтером в pre-commit;
  • зелёные тесты — обязательной проверкой в CI;
  • запрет на пуш в основную ветку — настройками репозитория.

Файл правил снимает рутину и уменьшает количество исправлений в диалоге. Он не заменяет ревью — что именно смотреть в сгенерированном коде, собрано в чек-листе ревью AI-кода. Что именно из этого получается в реальной работе, с цифрами и провалами, мы собрали в разборе вайбкодинга на практике.

Как завести за час

  1. Сгенерируйте черновик. У Claude Code для этого есть команда /init: агент читает репозиторий и собирает файл с командами, конвенциями и структурой. Она же подхватывает существующие правила Cursor и Copilot. Черновик придётся чистить: половина попавшего туда выводится из кода и только ест контекст.
  2. Оставьте 20–40 строк. Команды, границы, две-три договорённости, которые вы объясняете чаще всего. Остальное удалите.
  3. Работайте неделю как обычно. Каждый раз, когда вы поправляете агента второй раз подряд одной и той же фразой, дописывайте строку в файл. Это главный источник хороших правил.
  4. Разнесите по путям. Когда файл перевалит за две сотни строк, вынесите специфичное для фронтенда, бэкенда и тестов в правила с глобами: они подгружаются только при работе с этими файлами.
  5. Проверьте, что файл читается. В Claude Code это /context со списком загруженных файлов памяти, в Cursor — индикатор применённых правил в чате. Тихо не загрузившийся файл выглядит ровно как проигнорированный.
  6. Ревьюйте как код. Изменения правил проходят через тот же мердж-реквест: иначе через полгода никто не помнит, зачем там строка про особый порядок миграций.

Отдельно про монорепозитории: корневой файл описывает общее, а вложенные — специфику пакета. Так контекст не забивается правилами про фронтенд, когда агент правит Go-хендлер.

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

  • Файл на 800 строк. Растёт быстро, читается плохо, следуют ему всё хуже. Длинный файл — сигнал выносить части в правила с привязкой к путям.
  • Лозунги без критерия. «Соблюдай best practices» не меняет поведение агента ни на йоту.
  • Копия в четырёх форматах. Через месяц версии расходятся, и вы отлаживаете расхождение вместо кода.
  • Забытые устаревшие пункты. Правило про библиотеку, выпиленную в прошлом квартале, вредит молча.
  • Ожидание гарантий. Правила снижают частоту ошибок; жёстко запретить действие способны только хуки, линтер и CI.
  • Написали и не проверили. Пока файл не появился в списке загруженного контекста, он не работает.

С чего начать сегодня

Начните с одного файла в корне и пяти строк: команда тестов, команда линтера, запретные папки, формат коммитов, одна главная грабля проекта. Этого достаточно, чтобы следующая сессия началась сразу с задачи. Дальше файл растёт сам — из ваших же повторяющихся исправлений.

Следующий шаг после правил — дать агенту доступ к рабочим системам через MCP: базе, трекеру, документации. Как устроен протокол, разбираем в статье про MCP-серверы, а рабочие сборки — в подборке MCP-серверов.

В IT-ХОЗЯЕВА каждую неделю проходит воркшоп по vibe coding: участники приносят свои репозитории и разбирают такие настройки на живых задачах. Там же можно взять сессию с ментором из тарифа ХОЗЯИН за 2000 ₽/мес и пройтись по своему проекту предметно.

Правила для агента — это записанные договорённости команды, которые раньше жили в головах. Побочный эффект приятный: то, что вы формулируете для модели, обычно оказывается полезно и новому человеку в команде.