Как объяснить проект ИИ-агенту один раз, а не в каждом чате
Представьте интернет-магазин косметики. Вы ставите агенту — Claude Code или Codex — задачу на пять минут: добавить на карточку товара кнопку «Поделиться». На сайте таких кнопок уже штук пять, нужна шестая, точно такая же. Но агент в проекте первый день. Он не знает, где живут эти кнопки, как они собраны, какими командами проект запускается и куда лезть запрещено.
Дальше по классике. Без нормального входа в проект агент начинает читать всё подряд и сжигает лимиты. Вместо «ещё одной такой же» кнопки рисует свою, с нуля, не похожую на остальные. Попутно правит соседний блок, который никто не просил трогать. В конце жизнерадостно сообщает «готово» — при том что половина вёрстки поехала.
Именно от этого спасают файлы CLAUDE.md и AGENTS.md. Дальше разберём, какой из них нужен вам, что писать внутри, почему разросшийся файл начинает вредить и как поддерживать инструкции живыми.
Что это за файлы и какой нужен вам
CLAUDE.md и AGENTS.md — обычные текстовые файлы с лёгкой разметкой (формат Markdown), в которых лежат проектные инструкции для AI-агентов. По сути — короткий курс молодого бойца: что где лежит в проекте и как с ним обращаться.
Какой файл заводить, определяется инструментом. Claude Code читает CLAUDE.md и использует его как память проекта. Codex и другие агенты OpenAI читают AGENTS.md. Оба файла кладут в корень проекта. Работаете с двумя инструментами сразу — держите оба файла; проще всего сделать второй копией первого, содержимое у них почти совпадает. У Cursor схема похожая, но своя: есть Rules — его собственный формат правил проекта — и поддержка AGENTS.md. Туда записывают то, что редактор должен постоянно держать в голове.
Честная оговорка: гарантий эти файлы не дают. Anthropic пишет прямо — Claude старается придерживаться CLAUDE.md, но следует ему не всегда, особенно если инструкции размытые или противоречат друг другу. Тем не менее файл окупается: избавляет от повторных объяснений и помогает агенту быстро войти в проект.
Чем это отличается от README
Важно не перепутать: CLAUDE.md и AGENTS.md не заменяют README. У README устоявшаяся роль — вход для людей: разработчика, ревьюера, случайного гостя на GitHub. Он объясняет, что за проект, как его установить, запустить, настроить и проверить.
Сайт AGENTS.md специально разводит эти два слоя: README — людям, AGENTS.md — агентам, для инструкций по сборке, тестам и договорённостям, которые человеку в README только мешали бы. Так что файлы живут не вместо README, а рядом с ним: README рассказывает проект человеку, CLAUDE.md и AGENTS.md говорят агенту, что помнить в каждой сессии, какие команды гонять и какие границы не переступать.
Минимальный первый файл: что положить внутрь
Итак, есть проект и пустой файл. Вылизывать документ на все случаи жизни на старте не нужно — достаточно минимума, после которого агент перестаёт путаться:
- Что делает проект. Пара предложений, чтобы агент понимал, к чему прикручивает код.
- Стек: технологии и библиотеки, на которых всё собрано. Иначе агент притащит новую библиотеку туда, где задача решается имеющимися.
- Карта основных папок. Чтобы не искать ту самую кнопку по всему проекту.
- Как запустить проект локально. Точными командами, а не «запустите проект».
- Команды проверок: тесты, линт (автопроверка стиля и простых ошибок в коде), сборка (превращение исходников в готовое приложение), деплой (выкладка на боевой сайт). Чтобы «готово» не звучало без доказательств.
- Где искать уже написанные функции, прежде чем писать новые. Иначе появится третья реализация того, что уже сделано дважды.
- Что нельзя трогать без согласования. Чтобы одна кнопка «заодно» не превратилась в переписанную половину страницы.
- Как сдавать результат: что показать в конце, какие команды прогнаны, что прошло.
Практически тот же список рекомендует класть в AGENTS.md сам OpenAI: структура репозитория (папок с кодом проекта), команды запуска и сборки, тесты, договорённости, критерий готовности.
Для нашего магазина косметики первый CLAUDE.md может выглядеть так:
# CLAUDE.md — интернет-магазин косметики
## Что это за проект
Витрина косметики: каталог товаров, карточки, корзина, оформление заказа.
Заказы уходят во внешнюю CRM. Цель — продавать, поэтому скорость и SEO важны.
## Стек
- Next.js (App Router) + TypeScript + Tailwind — витрина и страницы.
- Node.js — бэкенд, простой API-слой.
- PostgreSQL — база с каталогом и товарами, доступ к базе через Prisma.
- Zod — проверка входящих данных на границе API.
## Где что лежит (карта папок)
- src/app — страницы и роуты (то, что видит покупатель).
- src/components — переиспользуемые кусочки интерфейса (кнопки, карточки).
- src/lib — работа с базой и внешними API (Prisma, CRM).
- src/content — тексты страниц и SEO-описания.
## Как запустить локально
- npm run dev — поднять сайт на своём компьютере для проверки.
## Команды проверок
- npm test — прогнать тесты (убедиться, что ничего не сломалось).
- npm run build — собрать проект как для боевого сервера.
- Деплой: git push в ветку main — дальше Vercel сам соберёт и выкатит.
## Прежде чем писать новое
- Сначала поищи готовое: UI-компоненты в src/components, работу с базой и CRM в src/lib.
- Не плоди дубли — если похожая функция уже есть, переиспользуй её.
## Трогать нельзя без моего согласия
- Страницу оплаты, корзину и интеграцию с CRM — сначала спроси, потом меняй.
## Как сдавать результат
- Коротко: что менял и зачем.
- Покажи, что npm test и npm run build проходят.
- Если менял внешний вид — приложи скриншот страницы.
Первый файл не обязан быть настолько подробным. Совсем маленькому проекту хватит трёх пунктов: что за проект, как запускать и проверять, что не трогать. Остальное допишется, когда проект подрастёт.
Пишите правила, которые агент может выполнить
Теперь про формулировки — от них зависит, работает файл или просто лежит. Размытое пожелание агент трактует как хочет, точную инструкцию выполняет буквально; то же самое советует Anthropic. Напишете «делай кнопки как надо» — агент сам решит, что такое «как надо», и сделает по-своему. Напишете «новую кнопку собирай из готового компонента Button, не рисуй с нуля» — выбора не останется.
Больше всего бесполезных правил в таких файлах — моральные наставления, которые агент спокойно игнорирует, потому что не понимает, что конкретно делать. Лечится переводом пожелания в действие, запрет, проверку или ссылку на конкретный документ. Формулировки ниже выросли из ошибок, которые у меня реально повторялись. Слева — как хочется написать, справа — как агент сможет выполнить:
- «Пиши чистый код» → «перед созданием нового сервиса найди существующие поиском по проекту через rg (быстрый поиск по файлам) и переиспользуй — или объясни, почему делаешь новый».
- «Не раздувай решение» → «меняй минимальный набор файлов, а отдельный рефакторинг (переделку кода без изменения того, что он делает) согласуй до правок».
- «Не ломай проект» → «перед сдачей запусти команды X, Y, Z и напиши, что прошло».
- «Смотри логи» → «бери безопасный маршрут из документа про логи, доступы по серверу не ищи».
Левая часть — оценка, которую агент не может проверить сам на себе. Правая — конкретное действие с понятным результатом. «Чистый код» каждый понимает по-своему, агент в том числе. «Найди существующие через rg и переиспользуй» проверяемо: либо искал, либо нет. Пример про логи — из моей практики: без документации агент ищет логи по серверу наугад, а одна строчка про безопасный маршрут сразу показывает, куда идти. Приватные пути и доступы в инструкцию при этом не пишут — только ссылку на документ с маршрутом.
Отсюда критерий хорошего правила: оно задаёт одно из пяти — действие, запрет, проверку, критерий готовности или ссылку на конкретный документ. Всё прочее — благие пожелания: звучат разумно, не работают.
Три уровня правил: глобальные, проектные и правила задачи
Проект у вас, скорее всего, не один. И часть правил повторяется везде: «отвечай по-русски», «пиши кратко», «не коммить без спроса». Копировать их в каждый проектный CLAUDE.md — лишний труд плюс риск, что где-то забудете обновить. Для таких правил есть один глобальный файл, который агент читает во всех проектах. Всего уровней три, у каждого своё место.
Глобальные инструкции — верно для всех проектов и всех чатов: «отвечай по-русски», «не коммить без просьбы», «не свети ключи и доступы», «предупреждай о рисках», «пиши кратко». Это ваши операторские правила. У Claude Code они живут в файле ~/.claude/CLAUDE.md, у Codex — в файле в его домашней папке ~/.codex. OpenAI рекомендует ровно такое разделение: личные настройки поведения — в глобальный файл, правила команды и кодовой базы — в файлы репозитория.
Рядом с магазином у вас наверняка живут другие проекты — лендинг, бот, ещё один сайт. «Отвечай по-русски» и «не коммить без спроса» одинаковы для всех — потому и лежат глобально. У предпринимателя, который сам код не пишет, глобальный файл может выглядеть так:
# Общие правила для всех проектов
## Кто я
- Я предприниматель, не программист. Код сам не читаю.
- Объясняй простыми словами, без жаргона. Термин ввёл — сразу расшифруй одной фразой.
- Отвечай по-русски.
## Как со мной работать
- Сначала короткий план на пару строк — что и зачем собираешься делать. Потом код.
- Дождись моего «да» на план, если правка большая или рискованная.
- Предупреждай о рисках ДО того, как что-то менять, а не после.
## Что без моего явного согласия делать нельзя
- Не коммить изменения.
- Не пушить и не деплоить (git push, выкатка на боевой сайт).
- Не удалять файлы и не сносить данные.
## Секреты и доступы
- Никогда не пиши пароли, ключи и токены в чат или в файлы.
- Нужен доступ — скажи, куда его положить самому (.env, секреты хостинга), сам ключ мне не показывай.
## Инструменты и зависимости
- Не тащи новую библиотеку, если задача решается тем, что уже есть в проекте.
- Меньше «магии»: простое понятное решение лучше хитрого.
Проектный файл — второй уровень: всё, что пригодится любому агенту, который работает над проектом сейчас или придёт потом. Стек, команды, структура, ограничения, проверки, где искать знания. Это и есть CLAUDE.md или AGENTS.md в корне.
Контекст задачи — третий уровень, всё сиюминутное: что делаем прямо сейчас, какие файлы уже обсудили, какое ограничение действует только в этой работе. В CLAUDE.md этому не место — устареет завтра же. Заведите отдельный файл задачи и держите такое там.
Куда класть правило, проверяется простым тестом. «Отвечай по-русски» — глобально: это про вас, не про проект. «Собирай через npm run build» — проектный файл: у соседнего проекта команда другая. «В этой задаче не трогаем оплату» — файл задачи: верно только сегодня. И поверх всех трёх уровней, отдельно и жирно: секреты, доступы и приватные маршруты не попадают никуда — ни в глобальный файл, ни в проектный, ни в задачу.
Почему длинный файл начинает вредить
Магазин растёт, и в его CLAUDE.md постепенно попадает всё: вёрстка, дизайн карточек, SEO, тексты для товаров, деплой, работа с CRM, правила ревью и десяток договорённостей. Всё в одном месте — на первый взгляд удобно.
А потом вы просите агента поднять SEO карточек, и по дороге он читает правила вёрстки и инструкцию по деплою. Зовёте агента-дизайнера поправить экран корзины — тот тащит в контекст логи, проверки и бизнес-правила. Кодеру достаются инструкции по SEO и текстам. Каждый получает весь ворох, хотя нужен один кусок.
Расплата за раздутый контекст — точность. Чем больше токенов (кусочков текста, которыми модель меряет объём, — примерно слово или его часть) попало в контекст, тем хуже модель их удерживает. У Anthropic для этого есть термин «context rot»: с ростом числа токенов падает точность, с которой модель вспоминает нужное. Внимание модели они описывают как бюджет, который тратится с каждым новым токеном, и вывод отсюда один — класть в контекст только необходимое под задачу. Вдобавок модель лучше помнит начало и конец длинного текста и проседает в середине — эффект так и называется, «потерялся в середине». Даже у моделей с огромным окном контекста качество на длинных входах заметно снижается.
Причём ломается всё плавно, без обрыва. Длинный файл не вырубит агента одномоментно — просто каждый лишний абзац понемногу уменьшает шанс, что нужное правило всплывёт и сработает. Насколько сильно — зависит от модели: свежие держат длинный контекст лучше, но эффект не исчезает совсем.
Заметьте, как поменялась проблема. В начале агент не знал о проекте ничего — мы дали ему файл. Теперь он знает слишком много лишнего под конкретную задачу: агенту, который чинит корзину, ни к чему правила дизайна карточек и тексты для товаров. Про то, что агенту нужен минимум полезного контекста, а не весь проект разом, я подробно писал в статье про два правила работы с ИИ-агентами.
Раз беда в лишнем знании, решение — дать агенту способ подтягивать под задачу только нужный кусок.
Превратите корневой файл в точку входа
Работает это так: корневой CLAUDE.md или AGENTS.md остаётся коротким маршрутизатором, а подробные знания переезжают в отдельные файлы по темам — код, дизайн, SEO, деплой (программисты зовут такие темы доменами). Корневому файлу не нужно пересказывать всё про архитектуру, логи и деплой. Его работа — направлять: задача про код — смотри сюда, про дизайн — туда, про SEO — вот документ, про деплой — вот этот.
OpenAI формулирует тот же принцип так: держите главный AGENTS.md коротким, а планирование, ревью и архитектуру выносите в отдельные документы, когда файл разрастается. У Anthropic это называется прогрессивным раскрытием: файл MEMORY.md работает как индекс, а тематические документы читаются по мере необходимости.
В динамике выглядит так: сначала один CLAUDE.md или AGENTS.md с базовыми правилами. Затем рядом вырастает папка docs/ или project-knowledge/ с отдельными документами — архитектура, стек, дизайн, SEO, контент, деплой, логи, тестирование, бизнес-правила. Затем добавляются файлы задач, чеклисты, hooks и CI — автоматические проверки, о них ниже.
Покажу на живом проекте. Свой сайт molyanov.ru я разрабатываю и поддерживаю агентами, и документация там устроена ровно по этой схеме. Корневые CLAUDE.md и AGENTS.md короткие — около 35 строк каждый, различаются одной строкой пути. Ключевая строка ведёт в базу знаний проекта — папку project-knowledge с гайдами по архитектуре, паттернам, git-процессу, UX, базе данных и деплою. Внутри папки — оглавление SKILL.md и пять доменных файлов: project.md (что за проект и для кого), architecture.md (стек, структура, модель данных), patterns.md (стандарты кода, git-процесс, SEO, тесты), deployment.md (платформа, окружения, откат, мониторинг), ux-guidelines.md (дизайн-система, доступность).
Маршрутизатором служит само оглавление SKILL.md. Вот реальный фрагмент — по нему агент выбирает, какой документ открыть (файл у меня на английском, привожу как есть):
## How to use
- Starting feature development — read project.md, architecture.md, patterns.md
- Working on data/content changes — read architecture.md (Data Model section)
- Working on UI/UX — read ux-guidelines.md
- Setting up deployment or monitoring — read deployment.md
- Creating branches or PRs — read patterns.md (Git Workflow section)
По-русски правило звучит так: пришла задача про интерфейс — агент открывает только ux-guidelines.md, задача про деплой — только deployment.md, а SEO живёт секцией внутри patterns.md, отдельного файла под него нет. Ни деплой, ни дизайн-гайд, ни правила текстов при этом в контекст не попадают. Корневой файл сам ничего не пересказывает — только направляет.
CLAUDE.md и AGENTS.md — верхний слой базы знаний проекта. Как вести саму базу — что уносить в отдельные документы, как держать контекст коротким — я разбирал в статье с 12 советами по вайбкодингу для неразработчиков.
Вернёмся к магазину — к этому моменту он дорос до той же схемы: минимальный стартовый CLAUDE.md превратился в короткий вход плюс доменные файлы, и конкретика под задачу живёт уже внутри них. Вот его architecture.md. Уносить к себе стоит не технологии из примера, а сами три заголовка — «Стек», «Где что лежит», «Важные пакеты». Это скелет, который вы заполните своими папками и своим стеком:
# Архитектура — интернет-магазин косметики
## Стек
- Next.js (App Router) — фронтенд и роутинг страниц.
- TypeScript — типизированный код (меньше случайных ошибок).
- Tailwind — стили через готовые классы.
- Node.js — бэкенд, простой API-слой.
- PostgreSQL — база данных: каталог и товары.
- Prisma — слой доступа к базе (запросы вместо ручного SQL).
- Zod — проверка входящих данных на границе API.
- Внешняя CRM — принимает заказы по API.
## Где что лежит
- src/app — страницы и роуты, которые видит покупатель.
- src/components — переиспользуемые UI-компоненты (кнопки, карточки товара).
- src/lib — работа с базой (Prisma) и внешними API (CRM).
- src/content — тексты страниц и SEO-мета (заголовки, описания).
## Важные пакеты
- @prisma/client — обращение к PostgreSQL из кода, схема базы в prisma/schema.prisma.
- zod — описываем форму входящих данных и отсекаем «мусор» до попадания в базу.
- next — сам фреймворк витрины (роутинг, рендер страниц, сборка).
- tailwindcss — оформление интерфейса, настройка в tailwind.config.ts.
Если половина слов незнакома — не страшно: их писал агент под конкретный стек. Тем, кто не программирует, важно не содержимое, а форма: файл отвечает на три вопроса — на чём проект сделан, где что лежит, какие пакеты трогать осторожно. Вот эту форму и забирайте.
Всю раскладку в живом виде я выложил в открытый репозиторий pavel-molyanov/molyanov-ai-dev на GitHub: там та же папка project-knowledge в шаблоне нового проекта, доменные файлы и инструменты, которыми база знаний наполняется. Документацию molyanov.ru целиком не публикую — в реальных файлах деплоя лежат доступы и приватные детали, так что публичный пример обезличенный. Сама база знаний — часть более широкого подхода к работе с агентами; целиком я описал его в статье про мой фреймворк агентной разработки: https://molyanov.ru/blog/freymvork-agentnoy-razrabotki-claude-code
Подпроектам — свои файлы правил
Бывает, под одной крышей живут сразу несколько проектов: сайт, админка, бот, документация, инфраструктура. Или монорепозиторий — один репозиторий, внутри которого несколько приложений или пакетов. Корневой файл задаёт общие правила, но внутри apps/site/, apps/admin/ или infra/ могут быть свои команды, свой стек, свои ограничения и проверки.
Тогда рядом с подпроектом кладут отдельный файл правил — CLAUDE.md, AGENTS.md или файл правил Cursor. Инструменты это умеют. Claude Code читает CLAUDE.md от папки, в которой идёт работа, поднимаясь к корню; файл во вложенной папке подхватывается, только когда агент туда заходит. Codex собирает инструкции от корня до текущей папки, и файл, который ближе, перекрывает более общие правила. Cursor поступает так же: вложенные правила важнее родительских. Механики чуть разные, идея одна — чем ближе файл к коду, тем ближе правила к делу.
Вложенный файл оправдан, когда в этой части проекта действительно другие команды, стек, ограничения или проверки. Если правило общее для всего проекта — ему место в корневом файле или в глубокой документации. Худший сценарий — расплодить одну и ту же копипасту по всем папкам: правило поменялось, вы уже не помните, в каком из пяти файлов его чинить, и копии тихо расходятся.
Критичные правила отдайте автоматике
Некоторые правила слишком важны, чтобы доверять их одной строчке текста. Возьмите «не пиши секреты» из глобального файла. Строчка в файле — лишь надежда, что агент вспомнит её в нужный момент. Надежда тем более шаткая, чем длиннее файл. Такое правило страхуют проверкой, которая не забывает.
OpenAI советует именно это: не полагаться на текст AGENTS.md, а подпереть его автоматикой, которая правила не просит соблюдать, а принуждает. Речь о программах, которые сами проверяют каждое изменение агента — гоняют тесты, сверяют код и формат, ищут утёкшие пароли и ключи — и не пропускают дальше то, что не прошло. И даже после рапорта «готово» стоит заглянуть в diff — список строк, которые агент изменил. Текст агент может проигнорировать, проваленную проверку — нет.
Инструментов несколько, каждый закрывает свой участок:
- Хук — маленькая программа, которая срабатывает сама в нужный момент. Например, PreToolUse в Claude Code перехватывает опасную команду до того, как агент её выполнит.
- pre-commit — запускает быстрые проверки при каждом сохранении изменений, а заодно gitleaks вылавливает случайно попавшие в код пароли и ключи.
- CI (например, GitHub Actions) — независимо проверяет изменения перед приёмкой: собирает проект, гоняет тесты, показывает результат.
- Проверка типов — следит, чтобы код не путал число с текстом.
Запоминать названия не нужно — агент настроит всё сам, если попросить. Важна сама возможность: критичное правило можно отдать автомату, и тогда оно не зависит от того, вспомнит ли агент строчку в файле.
Соответствие выглядит так. «Не коммить секреты» — страхует gitleaks или другой скан секретов: ловит ключи и пароли в изменениях. «Не ломай сборку» — build и проверка типов в CI: проект собирается, типы целы. «Пиши тесты» — критерий готовности плюс прогон тестов: рабочие сценарии остались рабочими. «Не ломай незаметно то, чем пользуются другие части системы» — тесты, контракт или ревью: ловят поломку договорённости между частями. «Докажи, что работа готова» — финальный ответ с командами, логами или скрином: оставляет человеку быстрый след проверки.
Частая ошибка тут — дублировать в инструкции то, что и так ловит линтер или форматтер. В одном исследовании файлов AGENTS.md такое дублирование оказалось самой распространённой проблемой: его нашли в 62% файлов выборки. Если проверку делает автоматика, правило в тексте не нужно — оно лишь раздувает файл и роняет ту самую точность, ради которой мы контекст подрезали.
И границы автоматики тоже стоит понимать: она ловит только механическое — проект собирается, секрет не утёк, тесты зелёные. Архитектурные решения и продуктовые риски она не видит, их ревьюит человек. Тесты и хуки снимают с ревью рутину, чтобы человек смотрел на важное.
Обновляйте файл после ошибок агента, а не по расписанию
CLAUDE.md и база знаний приносят пользу, только когда в них попадают правила из реальной работы. Файл, сгенерированный на старте, — это гипотеза о проекте. Рабочим он становится, когда вы дописываете туда то, обо что агент реально споткнулся.
Дальше цикл: агент ошибся → называем тип сбоя → выбираем правильный слой для исправления → проверяем, что ошибка не повторяется. OpenAI описывает ровно такой цикл обратной связи: обновляйте AGENTS.md, когда агент повторяет ошибку, читает лишние документы или раз за разом собирает один и тот же комментарий на ревью. Anthropic со стороны CLAUDE.md добавляет диагностику: убедитесь, что файл вообще загрузился, сделайте инструкцию конкретнее, поищите конфликтующие правила. А если действие должно срабатывать в строго определённый момент — нужен хук, текстом это не решается.
Ключевой шаг цикла — выбрать слой. По привычке всё летит в корневой файл, и зря: один и тот же сбой лечится в разных местах.
- Выдумал новую функцию вместо существующей — правило поиска в проектном файле плюс ссылка на архитектуру.
- Раздул решение — правило минимального набора изменений плюс согласование рефакторинга.
- Полез искать логи опасным путём — глубокий документ с безопасным маршрутом.
- Не запустил тесты — критерий готовности плюс CI.
- Ошибается только в одном модуле — локальная инструкция или модульный тест.
- Один и тот же спор на ревью — обновить чеклист задачи или правило приёмки.
Пункт про логи — ровно такой выбор слоя из моей практики: повторяющаяся боль уехала в отдельный документ и перестала переписываться в промпт заново каждый раз.
Чтобы цикл не держался на силе воли, обновление встраивают в процесс. У меня для этого есть команда /done: когда фича закончена, агент читает спеки и решения по ней, обновляет затронутые файлы базы знаний, архивирует задачу и коммитит изменения документации. Знание фиксируется не «когда-нибудь потом», а в момент завершения работы. Как вообще приучить агентов накапливать опыт, я разбирал отдельно: https://molyanov.ru/blog/nakoplenie-opyta-v-rabote-s-ii-agentami
Чеклист: проверьте свой файл
Пройдитесь по своему CLAUDE.md, AGENTS.md или правилам Cursor и честно ответьте:
- Понятно ли, какой агент читает этот файл: Claude Code — CLAUDE.md, Codex — AGENTS.md, Cursor — Rules или AGENTS.md?
- Отделены ли личные привычки от правил проекта?
- Есть ли базовый курс молодого бойца: команды запуска, тестов, линта, критерий готовности?
- Не превратился ли корневой файл в свалку обо всём?
- Ведут ли из него маршруты к доменным документам — или он пересказывает их содержимое?
- Есть ли карта, где искать существующие функции и глубокую документацию?
- Объясняют ли ссылки на документы, когда их читать, — или висят без контекста?
- Нет ли в файле секретов, приватных доступов и опасных команд?
- Правила конкретные и проверяемые? Критичное подпёрто хуком, тестом или CI?
- Не спорят ли между собой CLAUDE.md, AGENTS.md, правила Cursor, hooks и CI?
- Понятно ли, что обновлять после повторяющейся ошибки?
Если файла ещё нет или он давно стал свалкой, маршрут на сегодня такой. Создайте файл под свой инструмент. Напишите минимальный курс молодого бойца: стек, команды, карта папок, критерий готовности. Разведите глобальные привычки и проектные правила. Пухнущий файл разгрузите: доменные знания — в отдельные документы, в корне — маршруты к ним. Закрепите одну повторяющуюся ошибку в правильном слое: инструкции, документе, тесте, хуке или процессе. Через неделю вернитесь и удалите всё, что не помогает агенту принимать решения.
Эти файлы работают ровно до тех пор, пока остаются короткими, конкретными, проверяемыми — и пока вы поддерживаете их после реальных ошибок. Файл, который сгенерировали на старте и забыли, продублировали README и свалили туда всю документацию разом, превращается в тот самый шум, от которого мы уходили.