Как написать AGENTS.md, чтобы агент не гадал

Ниже — как написать файл за один вечер, подружить его с Claude Code и не превратить конституцию в простыню.

Зачем агенту отдельный файл, если уже есть README

README отвечает на вопрос «как человеку зайти в проект». Там быстрый старт, ссылки, скриншоты. Агент из этого редко понимает запреты. Он не видит, что вы «и так все знаете»: не трогать прод, не выкладывать черновик, не коммитить ключи.

Отдельный файл нужен, чтобы не повторять бриф. Открыли папку — агент уже знает правила. Закрыли чат, открыли новый — правила на месте. Это и есть настройка ИИ-агента без очередного эссе в промпте.

Практический критерий: если одно и то же ограничение вы произносите третий раз за неделю, оно должно жить в AGENTS.md, а не в голове.

Чем AGENTS.md отличается от CLAUDE.md, rules и SKILL.md

Путаница начинается с имён. Все похожи на «файл с правилами», но слои разные.

Когда хватит одного AGENTS.md

Один репозиторий, одна команда, агенты из разных редакторов. Вы не хотите поддерживать пять копий «не клади секреты в git».

Когда оставить Cursor rules или Claude skills

Разные правила для frontend/ и content/; повторяемый сценарий «собери семантику → положи в brief.md». Skill не заменяет конституцию. Конституция не должна содержать весь playbook навыка.

Системный промпт в настройках чата — ещё один сосед. Он живёт у вас в аккаунте, а не в git. Команда его не увидит. Для общего проекта берите файл в репозитории.

Что положить в файл: секции, которые агент реально читает

Спецификация не требует YAML и обязательных полей: это просто Markdown. Имеет смысл писать то, чего агент не выведет сам из кода.

1. Что это за проект — одно-два предложения: контент-завод, лендинг, бот. Без истории компании.
2. Команды — точные строки: как поставить зависимости, как прогнать проверку.
3. Запретные зоны — прод, секреты, сгенерированные папки, чужие роли.
4. Куда класть результат — draft.md, handoff.md, не в чат.
5. Критерий готово — что должно быть на диске, прежде чем агент скажет «сделал».

Команды сборки и проверки

Пишите команды так, как их запускаете сами. Если отдельного теста нет — не выдумывайте npm test. Агент охотно запустит то, чего в репозитории нет, и объявит провал.

Запретные зоны и секреты

В AGENTS.md пишите куда их класть (переменные окружения, секреты облака), а не сами ключи. Файл попадёт в git.

Шаблон AGENTS.md на одну страницу

Скопируйте, замените скобки. Это пример для контент-команды, не для монорепы на тысячу пакетов.

# AGENTS.md

## Проект
Русскоязычный контент-завод: лонгриды и страницы для сайта. Язык ответов — русский.

## Куда писать
- Черновик текста — `draft.md`
- Короткий статус после работы — `handoff.md`
- Не публиковать на сайт и не выкладывать в Telegram без явной команды человека

## Запреты
- Не коммитить ключи, пароли, токены
- Не выдумывать частоты Wordstat и цифры «экономии часов»
- Не переписывать этот файл без просьбы

## Как проверить работу
1. Открыть `draft.md` — есть H1 и текст длиннее 500 знаков
2. Открыть `handoff.md` — есть статус, что сделано, что блокирует
3. Секретов в git-диффе нет

## Команды
Отдельного теста нет. Не запускай деплой.

Шаги, чтобы файл начал работать:

Признак успеха: агент создал draft.md и в handoff.md написал, что публикацию не делал. Если он сразу предлагает «выложить» — запрет сформулирован слабо, усильте глаголом «нельзя» и местом, куда класть результат.

Типичные осечки новичка: файл назвали agents.md в другой папке; положили в .cursor/ вместо корня; написали «будь осторожен с публикацией» вместо «не публиковать».

Как подружить Cursor, Codex и Claude Code без двух конституций

Cursor читает AGENTS.md в корне и во вложенных папках. CLI Cursor дополнительно подхватывает CLAUDE.md рядом с правилами .cursor/rules. Codex и многие другие клиенты ждут именно AGENTS.md. Claude Code исторически заточен на CLAUDE.md.

Не ведите две полные копии: они разъедутся через неделю.

Рабочая схема mix-команды:

• Закон проекта — один: AGENTS.md.
• Для Claude Code в корне тонкий CLAUDE.md с первой строкой @AGENTS.md или символическая ссылка CLAUDE.md → AGENTS.md (на Windows ссылки капризнее, импорт надёжнее).
• В CLAUDE.md ниже — только то, что специфично для Claude: хуки, план-режим, свои команды.
• .cursor/rules — только если правило должно срабатывать на *.php и не на черновики.

Оплата и доступ из РФ: Cursor и Claude Code часто требуют иностранную карту или посредника. Codex завязан на экосистему OpenAI. AGENTS.md от этого не зависит: файл лежит у вас в git и работает в том клиенте, который команда реально открывает. Не копируйте конституцию в каждый SaaS «на всякий случай».

Вложенные AGENTS.md в большом репозитории: кто побеждает

Если папок много, в подпроекте можно положить второй AGENTS.md. Агент берёт ближайший к файлу, с которым работает. Более узкий файл побеждает широкий. Сообщение в чате побеждает оба.

Для контент-завода это удобно так:

• корень: язык, секреты, запрет публикации;
• wordpress-theme/AGENTS.md: не ломать hero и canvas;
• drafts/AGENTS.md: можно черновики, нельзя деплой.

Не плодите десять файлов «на будущее». Второй файл появляется, когда корневой начинает спорить сам с собой: «в теме можно править PHP, в текстах нельзя».

Handoff и память: что не пихать в конституцию проекта

Конституция не меняется каждый час. Состояние задачи — меняется. Их мешать нельзя.

В handoff.md держите: цель, статус, блокеры, путь к артефакту. Не копируйте туда весь чат. Не кладите в AGENTS.md фразы вроде «сегодня пишем про скидку 20%» — это сгорит завтра и будет врать агенту неделю.

Отдельные базы памяти и wiki — следующий уровень. Сначала заставьте работать два файла: конституция + короткий журнал. Если агент снова просит бриф, журнал пустой или конституция слишком общая.

Как проверить, что агент слушается файла, а не чат

Не верьте ответу «я учёл правила». Устройте контрольную.

1. В AGENTS.md напишите запрет, который легко нарушить: «не используй слово “уникальный” в draft.md».
2. Попросите написать короткий абзац в draft.md.
3. Откройте файл. Если слово на месте — агент файл не применил (не тот путь, не тот клиент, слишком длинный AGENTS.md, запрет спрятан в конце простыни).
4. Исправьте файл, не промпт. Повторите на новом чате без копипаста правил.

Второй тест: попросите «опубликуй на сайт». Правильный агент откажется и укажет на запрет. Если сразу ищет пароль — конституция не сработала.

Типичные ошибки: простыня, секреты, «будь полезным»

Файл только в чате. Сгенерировали шаблон, не сохранили в корень — следующий агент его не увидит.

Первый вечер: контент-команда без разработчика

Сценарий: вы ведёте Telegram и черновики в папке Google-диска или git. Агент в Cursor или Codex должен писать посты, но не слать их сам.

1. Соберите в одну папку: бренд (тон, стоп-слова), 2–3 удачных поста, пустой draft.md.
2. Положите AGENTS.md из шаблона выше. В запреты добавьте названия каналов: «не писать в @maya_pro и MAX».
3. Напишите в чат: «прочитай AGENTS.md, сделай черновик поста в draft.md по теме X, в каналы не публикуй».
4. Откройте draft.md глазами. Проверьте стоп-слова и факты.
5. Только после этого копируете текст в Telegram сами или отдельным сценарием Make/n8n — это уже другой слой, не конституция.

Признак успеха вечера: новый чат без копипаста брифа всё равно не лезет в публикацию и кладёт текст в тот же файл. Если агент снова спрашивает «куда писать» — в AGENTS.md нет секции «Куда писать» или файл лежит не в корне открытой папки.

Ошибка «я не программист, мне это не для меня»: вам не нужен монорепозиторий и 88 вложенных файлов. Нужен один markdown на русском и привычка не держать правила только в чате.

Когда конституция лежит в git, следующий шаг — не ручной копипаст в Telegram, а сценарий. Разбор Make и агентных цепочек: обучение по автоматизации на kv-ai.ru. Тема Cursor/IDE: редактор — Cursor по реферальной ссылке.