VibeCoderzVibeCoderz
Все статьи
Вайбкодинг: гайды2026/07/078 мин чтения

CLAUDE.md и AGENTS.md: как настроить AI-агента для своего pet project

Оптимизируйте настройку AI-агента всего за пару минут: добавьте в корень репозитория CLAUDE.md или AGENTS.md с инструкциями, и ваш агент сразу поймет стек, структуру и правила проекта.

Содержание (10)+

Хотите сделать проект с помощью нейросети и чтобы агент не переспрашивал одно и то же на десятом сообщении? Ответ простой: положите в корень репозитория один файл с инструкциями. 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 CodeCLAUDE.mdНативная, три уровня памяти
CursorAGENTS.mdНативная с июня 2026
WindsurfAGENTS.mdНативная с июня 2026
GitHub CopilotAGENTS.mdНативная с августа 2025
Codex CLIAGENTS.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 выделяет шесть повторяющихся блоков. Начинайте с команд, а не с описаний: агент читает файл в начале каждой сессии и первым делом должен видеть, чем запустить проект.

  1. Команды. npm run dev, npm run test, точные флаги, которые вы реально используете.
  2. Структура проекта. Вывод команды tree работает лучше длинного текста.
  3. Стек с версиями. Не просто «React», а «React 18 с TypeScript 5.3 и Vite».
  4. Стиль кода. Один пример хорошо/плохо вместо абзаца объяснений.
  5. Git-конвенции. Формат коммитов, именование веток.
  6. Границы. Что агент никогда не должен делать без вашего явного «да».

Для 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.

Автор

Максим Наговицын

Маркетинг-стратег, IT-предприниматель, ментор по вайбкодингу

2026/07/07

10+ лет в маркетинге, 300+ клиентских проектов: сайты, реклама, боты. Создатель GoBanana (228K+ пользователей, 11.6 млн ₽ выручки) и VibeCoderz. Делаю AI-продукты сам через Claude Code, Cursor, Windsurf и консультирую тех, кто хочет так же.

Об авторе →
All Posts

Инструменты, упомянутые в статье

Читать далее

📄 Статья

Playwright MCP: подключаем браузер к Claude Code и Codex

Playwright MCP — это официальный MCP-сервер от Microsoft, который даёт агенту вроде Claude Code или Codex доступ к настоящему браузеру: агент открывает страницу, кликает, заполняет формы и сам смотрит, что получилось. Обновлено: август 2026. Ниже — п…

2026/08/268 мин
📄 Статья

NeuralDeep: российский каталог скиллов для AI-агентов — Яндекс, 1С, Wildberries, Битрикс24

Новый российский каталог NeuralDeep в 74 навыках для AI-агентов, включая Яндекс, Wildberries и Битрикс24, плюс собственный LLM‑API на российских GPU. Это решение без «skills.sh» и с соблюдением 152‑ФЗ.

2026/06/2410 мин
📄 Статья

Claude Code vs GitHub Copilot 2026: когда использовать каждый

Claude Code и GitHub Copilot в 2026 году уже не просто автокомплиторы: один работает как автономный терминальный агент, а второй интегрирован в IDE и предлагает код в реальном времени. В статье сравниваются их возможности, цены и лучшие сценарии использования.

2026/04/2810 мин
📄 Статья

Claude Code Terminal и CLI 2026: запуск, команды и отличие от IDE

Claude Code CLI – это терминальный агент, который читает ваш проект, вносит правки и запускает команды автоматически, без копирования кода в чат. Он отличается от IDE‑плагинов тем, что полностью интегрируется в командную строку и управляется флагами.

2026/04/288 мин
📄 Статья

Полный гайд по OpenAI Codex 2026 — суперприложение для вайбкодинга

Codex 2026 позволяет писать, запускать и управлять кодом, браузером и документами в одном окне, превращая любой проект в автоматизированное приложение без лишнего переключения.

2026/04/2116 мин
📄 Статья

Claude vs ChatGPT для вайбкодинга 2026: кто реально лучше пишет код

Claude доказал свою мощь в вайбкодинге 2026: он генерирует более точный, читаемый код, а контекст до 1 млн токенов повышает продуктивность, что заставило большинство разработчиков перейти от ChatGPT.

2026/04/178 мин