Когда я открываю новый проект в Cursor, в репозиторий первым делом летит AGENTS.md. Не README, не папка docs, не комментарии в коде. AGENTS.md — это короткий файл, который объясняет ИИ-агенту, что можно трогать, что нельзя, и какие у нас тут правила. Один файл, пять-десять минут чтения, и новая сессия Cursor или Claude Code перестаёт ломать проект.

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

Ключевое правило: AGENTS.md — это не договор с человеком. Это шпаргалка для ИИ. Пишите простыми словами, как для коллеги, который зашёл в проект впервые и не хочет ничего сломать.

Что вообще такое AGENTS.md

AGENTS.md — это конвенция, которую поддерживают Cursor, Claude Code, Aider, Continue и большинство современных ИИ-агентов для кода. Файл лежит в корне репозитория (или в корне монорепы, в подпапке). Агент читает его автоматически при старте сессии и использует как набор правил: что менять можно, что нельзя, как запускать тесты, какой стиль кода предпочтителен.

Это аналог README, только для машины. README пишется для человека, который заходит на GitHub. AGENTS.md — для агента, который заходит в ваш проект и собирается писать код.

Почему этого не заменяет системный промпт или длинный README

Я проверял. Системный промпт в Cursor работает, но: первое — он один на все проекты, его нельзя сделать разным для бэкенда и фронта; второе — агенты часто игнорируют длинные инструкции, особенно когда задача простая («поправь опечатку»).

README — отличный формат, но он для людей. Когда я пишу в нём «используем TypeScript и Next.js», я объясняю архитектурные решения для разработчика. Когда я пишу в AGENTS.md «не трогай файлы в src/legacy/ — там легаси, которое нельзя рефакторить без согласования», я объясняю агенту границы дозволенного. Разные задачи — разные файлы.

Когда AGENTS.md действительно нужен

  • Проект больше одного экрана кода — агенту нужен контекст структуры
  • В проекте есть зоны «не трогать» (легаси, сгенерированный код, чужие пакеты)
  • Команда или вы сами возвращаетесь к проекту через месяцы — нужен файл, который напомнит правила
  • Используете несколько агентов в разных IDE — единый файл удобнее, чем настройки в каждой

Для простого скрипта на 50 строк AGENTS.md избыточен. Для проекта, который будет жить дольше одного вечера — почти всегда оправдан.

Что писать в AGENTS.md: 7 обязательных блоков

Я выделяю семь блоков, которые закрывают 90 процентов случаев. Не обязательно писать длинно — главное, чтобы каждый блок был понятен агенту без догадок.

1. Цель проекта — что делаем и зачем

Один-два абзаца: что это за проект, для кого, какую проблему решает. Агент с этой информацией делает более точные предположения. Пример: «Магазин здорового питания с доставкой по Петрозаводску, целевая — мамы с детьми до 5 лет». Не «интернет-магазин».

2. Текущее состояние — что уже работает

Список того, что уже реализовано: «готова авторизация, корзина, оплата через Юкассу; не готово — личный кабинет, история заказов». Агент не будет предлагать писать авторизацию заново.

3. Стек и команды запуска

Коротко: язык, фреймворк, база данных, пакетный менеджер. И — обязательно — команды, которые нужно знать агенту:

npm run dev      # локальный сервер
npm run build    # прод-сборка
npm run test     # тесты
npm run lint     # проверка стиля

Без этих команд агент не сможет проверить, что его изменения не сломали проект. А с этими командами — сможет.

4. Границы и зоны «не трогать»

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

  • src/legacy/ — старый код, рефакторинг только после согласования
  • src/generated/ — сгенерированный код, править бессмысленно, перегенерируется
  • vendor/ и node_modules/ — чужие пакеты
  • .env, secrets/, credentials/ — секреты, не читать и не коммитить

5. Стиль кода — что предпочтительнее

Короткий список правил: используем функциональные компоненты, избегаем any в TypeScript, имена переменных — английские, комментарии — на русском. Без эссе — по пунктам.

6. Типичные задачи — примеры запросов

Три-четыре примера того, что вы обычно просите у агента в этом проекте. Не копипаст промптов, а формулировки: «добавить новый роут в /api/orders», «обновить компонент карточки товара под новый дизайн», «написать миграцию для нового поля в orders».

7. Проверка перед коммитом

Чеклист из 3-5 пунктов: прогнать тесты, проверить линтер, обновить документацию в /docs, проверить, что новые секреты не утекли в код. Этот блок дисциплинирует и вас, и агента.

Минимум, который можно начать с завтрашнего дня

Если у вас нет времени на семь блоков — начните с трёх: цель проекта, стек и команды, границы «не трогать». Уже через неделю вы заметите, что агент перестал ломать легаси и предлагать «давайте всё перепишем на Rust».

Дальше — добавляйте стиль, типичные задачи, чеклист. Через месяц файл вырастет до 30-50 строк, и это нормально. Главное — он живой, вы обновляете его, когда меняется архитектура или появляются новые «зоны не трогать».

Главная мысль

AGENTS.md — это маленький файл с большим эффектом. Он превращает ИИ-агента из «умного гостя, который тыкает во всё подряд» в «коллегу, который знает ваши правила и работает по ним». Десять минут работы экономят часы правок после.

Если захотите — у меня есть шаблоны AGENTS.md под Next.js, Python-бэкенд, Telegram Mini App и data-проекты. Могу поделиться и разобрать ваш проект. @vorobeoff.

По теме