Хотите сделать проект с помощью нейросети и чтобы агент не переспрашивал одно и то же на десятом сообщении? Ответ простой: положите в корень репозитория один файл с инструкциями. CLAUDE.md — для Claude Code, AGENTS.md — для всех остальных: Cursor, Windsurf, Codex, Copilot.
Ниже пошагово: что писать в файл, какая структура работает, и готовый шаблон, который можно скопировать прямо в свой pet project.
По данным анализа более 2500 репозиториев на GitHub, файлы с инструкциями для агента сокращают время настройки новой AI-сессии с 20-40 минут до пары минут. Ниже: разница между CLAUDE.md и AGENTS.md, готовый шаблон под 30-50 строк и пять ошибок, которые обнуляют весь эффект.
Обновлено: октябрь 2026.

Зачем вообще нужен файл инструкций для AI-агента?
Без файла инструкций агент каждую сессию заново гадает ваш стек, структуру папок и правила кода. С файлом он получает это за секунду, до первого промта.
У языковых моделей нет памяти между сессиями. Каждый чат начинается с нуля. Если создать проект с помощью нейросети без файла контекста, придется каждый раз объяснять агенту одно и то же: какой стек, где лежат компоненты, что нельзя трогать. Это тратит и ваше время, и токены.
Именно эту дыру закрывают CLAUDE.md и AGENTS.md. Файл лежит в корне репозитория, агент читает его автоматически при старте сессии. Дальше он уже знает: React или Vue, где база данных, какой командой запускать тесты. Не нужно пересказывать это заново в каждом промте.
Для pet project это особенно ценно. Обычно такой проект ведет один человек, без ревью и без второго разработчика, который поправит агента. Файл инструкций в этом случае работает как ваш заместитель: держит правила, пока вас нет рядом.

Чем отличаются CLAUDE.md и AGENTS.md?
CLAUDE.md — родной формат Claude Code с поддержкой уровней памяти. AGENTS.md — открытый стандарт, который читают Cursor, Windsurf, Codex и еще два десятка инструментов без доработок.
К середине 2026 года AGENTS.md стал стандартом де-факто: его читают нативно Codex CLI, GitHub Copilot, Cursor, Windsurf, Amp, Aider, Zed, Devin и JetBrains Junie. Стандарт курирует Agentic AI Foundation при Linux Foundation, а среди авторов исходной идеи — OpenAI, Google, Cursor и Factory (agents.md).
Claude Code стоит особняком. По официальной документации Anthropic, инструмент читает именно CLAUDE.md и не подхватывает AGENTS.md автоматически (Claude Code Docs). Запрос на поддержку AGENTS.md висит в GitHub Issues с марта 2026 года и собрал тысячи реакций, но ответа от команды пока нет (GitHub Issue #34235).
| Инструмент | Файл | Поддержка на июль 2026 |
|---|---|---|
| Claude Code | CLAUDE.md | Нативная, три уровня памяти |
| Cursor | AGENTS.md | Нативная с июня 2026 |
| Windsurf | AGENTS.md | Нативная с июня 2026 |
| GitHub Copilot | AGENTS.md | Нативная с августа 2025 |
| Codex CLI | AGENTS.md | Нативная (соавтор стандарта) |

Как совместить CLAUDE.md и AGENTS.md в одном pet project?
Держите общие правила в AGENTS.md, а CLAUDE.md сделайте тонким файлом-мостиком, который просто импортирует AGENTS.md через символ @.
Если хотите пользоваться и Claude Code, и Cursor в одном проекте, не дублируйте правила в двух файлах. Общие вещи, стек, структуру, границы, пишите один раз в AGENTS.md. Cursor и Windsurf подхватят его сами. Для Claude Code в корне создайте короткий CLAUDE.md:
@AGENTS.md
## Специфика для Claude Code
- Используй Plan Mode для изменений в /src/api
- Предпочитай subagent для написания тестовСимвол @ перед именем файла в CLAUDE.md означает импорт содержимого. Так Claude Code получает те же правила, что и остальные инструменты, плюс свои настройки поверх. Это официально рекомендованный Anthropic способ синхронизации, пока нативная поддержка AGENTS.md не появилась.
Как написать AGENTS.md, чтобы агент его реально слушал?
Лучшие файлы короткие: 30-50 строк, с реальными примерами кода вместо описаний стиля. Исследование GitHub показало, что файлы длиннее 150 строк почти не улучшают результат, а инференс дорожает на 20-23%.
Главная ошибка — просить нейросеть сгенерировать AGENTS.md целиком. Исследование, на которое ссылается разбор best practices, показало: сгенерированные LLM файлы инструкций снижали успешность задач в 5 из 8 протестированных сценариев и добавляли по 2-4 лишних шага на каждую задачу (betterclaw.io). Причина проста: модель пишет общие фразы вроде «следуй лучшим практикам», которые агент и так знает.
Работает другой подход. Возьмите команду /init в Claude Code как черновик, а дальше вручную впишите специфику именно вашего проекта. Например, вместо «пиши чистый код» дайте один реальный пример: как выглядит хороший компонент у вас, а как плохой. Один пример кода стоит больше трех абзацев объяснений.
Обязательно пропишите границы: что агенту трогать нельзя. Самое частое правило из анализа тысяч репозиториев — «никогда не коммить секреты». Для pet project добавьте свое: не трогать папку /legacy, не запускать git push без спроса, не удалять миграции.

Какая структура файла работает лучше всего?
Шесть блоков покрывают почти все реальные потребности агента: команды, структура проекта, стек с версиями, стиль кода на примерах, git-конвенции и явные границы.
Анализ GitHub-репозиториев с рабочими AGENTS.md выделяет шесть повторяющихся блоков. Начинайте с команд, а не с описаний: агент читает файл в начале каждой сессии и первым делом должен видеть, чем запустить проект.
- Команды.
npm run dev,npm run test, точные флаги, которые вы реально используете. - Структура проекта. Вывод команды
treeработает лучше длинного текста. - Стек с версиями. Не просто «React», а «React 18 с TypeScript 5.3 и Vite».
- Стиль кода. Один пример хорошо/плохо вместо абзаца объяснений.
- Git-конвенции. Формат коммитов, именование веток.
- Границы. Что агент никогда не должен делать без вашего явного «да».
Для pet project не нужны все шесть сразу. Начните с трех первых блоков и добавляйте остальные по мере трения, то есть когда агент реально начнет ошибаться в чем-то конкретном.
Готовый шаблон CLAUDE.md / AGENTS.md для pet project
Шаблон ниже покрывает типичный pet project на Next.js. Скопируйте, замените стек и команды на свои, уберите то, что не подходит.
# Мой pet project
## Стек
- Next.js 14, TypeScript, Tailwind CSS
- База данных: SQLite через Prisma
- Тесты: Vitest
## Команды
- npm run dev — запустить локально
- npm run test — прогнать тесты
- npm run build — обязательно перед коммитом
## Структура
/src/app — страницы
/src/components — компоненты
/prisma — схема базы данных
## Стиль кода
Плохо:
function getData(x) { return fetch(x).then(r => r.json()) }
Хорошо:
async function getData(url: string): Promise<Data> {
const response = await fetch(url);
return response.json();
}
## Границы
- Никогда не коммить .env файлы
- Не трогать /prisma/migrations руками, только через prisma migrate
- Не запускать git push без явной просьбыЭтого достаточно для старта. Дальше файл растет через трение: каждый раз, когда агент ошибается одинаково, добавляйте строку с правилом, а не переписывайте промт заново.
Какие ошибки чаще всего убивают эффективность этих файлов?
Три ошибки встречаются чаще всего: файл слишком длинный, файл сгенерирован моделью целиком, файл содержит устаревшую информацию о стеке.
Длинный файл не значит хороший файл. Технический потолок AGENTS.md — 32 КиБ, но практический предел эффективности — примерно 150-200 строк (iuriio.com). После этого агент тратит внимание на текст, который не относится к текущей задаче.
Вторая ошибка — устаревшие данные. Файл, который ссылается на библиотеку, которую вы уже выпилили из проекта, хуже, чем отсутствие файла вообще: он активно вводит агента в заблуждение. Обновляйте CLAUDE.md/AGENTS.md сразу, когда меняете архитектуру, а не когда-нибудь потом.
Третья ошибка, характерная именно для pet project: секреты в файле. Он часто попадает в публичный репозиторий на GitHub. Никаких реальных ключей и паролей, только ссылки на то, где они хранятся.
Максим: «Портал VibeCoderz мы собрали за неделю тремя скриптами голосом в Claude Code, 6 200 материалов на выходе. Но это сработало только потому, что агент с первого дня знал структуру контента и что нельзя трогать. Без файла с правилами это была бы неделя переспрашиваний, а не неделя работы».

Кому нужен только один файл, а кому оба?
Если работаете только в Claude Code — хватит одного CLAUDE.md. Если переключаетесь между Cursor, Windsurf и Claude Code — нужен AGENTS.md как основной источник правды и тонкий CLAUDE.md-мостик поверх.
| Ситуация | Что использовать |
|---|---|
| Только Claude Code, соло-проект | Один CLAUDE.md |
| Только Cursor или Windsurf | Один AGENTS.md |
| Cursor + Claude Code вместе | AGENTS.md + CLAUDE.md с @AGENTS.md |
| Планируете открыть исходники | AGENTS.md — его прочитает любой контрибьютор с любым агентом |
Для большинства pet project, где вы пробуете создать проект нейросетью через связку Cursor и Claude Code, вторая схема из таблицы экономит время: правила пишутся один раз, а работают в обоих инструментах.

FAQ
Обязательно ли называть файл заглавными буквами AGENTS.md?
Да. Стандарт требует именно верхний регистр, agents.md в нижнем регистре некоторые инструменты не подхватят. Для CLAUDE.md то же самое правило.
Можно ли доверить генерацию файла самой нейросети?
Частично. Команда /init в Claude Code дает неплохой каркас, но исследования показывают, что полностью сгенерированные файлы часто снижают качество работы агента. Каркас сгенерировать можно, довести вручную нужно обязательно.
Что делать, если Cursor и Claude Code выдают разный результат на одинаковых инструкциях?
Это нормально. У каждого инструмента свой harness, то есть обвязка вокруг модели: то, как она читает файлы и вызывает инструменты. Одни и те же правила в AGENTS.md могут сработать чуть иначе в разных harness.
Нужен ли AGENTS.md для совсем маленького скрипта на 50 строк?
Нет смысла. Файл окупается, когда проект растет за пределы одной сессии в голове: несколько модулей, повторяющиеся задачи, работа в несколько заходов.
Как агент поймет, какой файл главнее, если их несколько в разных папках?
По конвенции стандарта побеждает файл, ближайший к редактируемому пути. Корневой AGENTS.md задает общие правила, вложенный в подпапке переопределяет их локально.
Можно ли хранить в файле реальные API-ключи для удобства?
Нет. Файл нужно считать потенциально публичным: в него легко закоммитить лишнее, и он может утечь при публикации репозитория. Только ссылки на хранилище секретов, никогда сами секреты.
Что лучше: одна большая инструкция или несколько файлов по папкам?
Для pet project обычно хватает одного корневого файла. Несколько файлов по папкам имеет смысл, когда проект дорастает до монорепозитория с явно разными частями: фронтенд, бэкенд, инфраструктура.

Что почитать дальше на VibeCoderz
Подробный разбор настройки самого Claude Code, включая Plan Mode, хуки и субагентов, есть в гайде по Claude Code. Если выбираете между инструментами, посмотрите обзоры Cursor и Windsurf в каталоге.
Нужна помощь с настройкой рабочего процесса под конкретный pet project? Запишитесь на консультацию к Максиму.
Обновлено: октябрь 2026.