Допустим, у вас магазин косметики на WooCommerce. Вы просите агента — Claude Code или Codex — добавить на карточку товара кнопку «Поделиться». Дело на пять минут: таких кнопок на сайте уже штук пять, нужна шестая, ровно такая же.
Вот только для агента это первый день на работе. Он не знает, где лежат эти кнопки, как они устроены, какими командами собираются стили и что в проекте трогать нельзя.
Дальше сценарий предсказуемый. Он лезет читать всё подряд и жжёт лимиты. Вместо «ещё одной такой же» лепит кнопку с нуля, не похожую на остальные. Заодно правит соседний блок, который его не просили трогать. В конце бодро сообщает «готово», хотя половина вёрстки съехала. Открываете новый чат — и всё сначала: агент как будто с амнезией.
Ровно эту проблему решают CLAUDE.md и AGENTS.md. Это обычные текстовые файлы с лёгкой разметкой Markdown, куда складывают проектные инструкции для агента: короткий курс молодого бойца — где что лежит и как с этим работать. Claude Code читает CLAUDE.md, Codex и другие агенты OpenAI читают AGENTS.md. Оба живут в корне проекта. Работаете с двумя инструментами — держите оба файла, второй проще всего сделать копией первого: содержимое почти одинаковое. У Cursor логика та же, но своя система: у него есть Rules и поддержка AGENTS.md.
Гарантий эти файлы не дают. Anthropic прямо пишет: Claude старается держаться CLAUDE.md, но следует ему не всегда — особенно если инструкции расплывчатые или спорят друг с другом. Даже так файл экономит повторные объяснения и заметно ускоряет вход агента в проект.
Что положить в первый CLAUDE.md и AGENTS.md
Вылизывать документ на все случаи жизни сразу не нужно. На первом заходе хватит минимума, после которого агент перестаёт путаться:
- Что делает проект. Одно-два предложения, чтобы агент понимал, к чему прикручивает код.
- Стек. На чём всё сделано — чтобы агент не притащил библиотеку туда, где задача решается имеющимся.
- Карта папок. Где что лежит, чтобы он не искал ту самую кнопку по всему проекту.
- Как запустить локально. Точные команды, а не «запустите проект».
- Команды проверок: тесты, линтер, сборка, выкладка. Чтобы «готово» подкреплялось доказательством.
- Где искать существующее перед тем, как писать новое. Чтобы не появилась третья реализация того, что уже написано дважды.
- Что нельзя трогать без согласования. Чтобы одна кнопка «заодно» не превратилась в переписанную половину страницы.
- Как сдавать результат. Что показать в конце: какие команды прогнал, что прошло.
Примерно тот же список рекомендует класть в AGENTS.md сам OpenAI: структура репозитория, команды запуска и сборки, тесты, договорённости и критерий готовности.
Главное в формулировках — конкретность. Размытое пожелание агент понимает как хочет, точную инструкцию выполняет буквально. Напишете «делай кнопки как надо» — он сам решит, что такое «как надо». Напишете «новую кнопку собирай из существующего шаблона, не рисуй с нуля» — выбора не останется.
Собираем это для нашего магазина, и первый CLAUDE.md выглядит так:
# CLAUDE.md — интернет-магазин на WooCommerce
## Что это за проект
Магазин косметики на WordPress + WooCommerce: каталог, карточки товара,
корзина, оплата картой и через СБП. Заказы уезжают в 1С по расписанию.
## Стек
- WordPress 6.x, WooCommerce, PHP 8.2, MySQL 8.
- Дочерняя тема `themes/shop-child` — вся вёрстка магазина.
- Свой плагин `plugins/shop-integration` — обмен с 1С и приём платежей.
- Стили: Sass → CSS через `npm run build`, исходники в `assets/scss`.
## Где что лежит
- `themes/shop-child/woocommerce/` — переопределённые шаблоны магазина.
- `themes/shop-child/inc/` — хуки, фильтры, регистрация сущностей.
- `plugins/shop-integration/src/` — обмен, платежи, очереди.
- `assets/scss/` — исходники стилей. Править только здесь, не готовый CSS.
## Как запустить локально
- `docker compose up -d` — поднять сайт и базу.
- `npm run build` — пересобрать стили после правки Sass.
## Команды проверок
- `composer lint` — PHPCS по стандарту WordPress.
- `npm run build` — стили собираются без ошибок.
## Прежде чем писать новое
- Ищи готовое: хуки в `inc/`, шаблоны в `woocommerce/`.
- Кнопки и карточки собирай из существующих шаблонов, а не с нуля.
## Трогать нельзя без моего согласия
- Приём платежей, обмен с 1С, `wp-config.php`, таблицы заказов.
## Как сдавать результат
- Что менял и зачем — две строки.
- Покажи, что `composer lint` и `npm run build` проходят.
- Менял вёрстку — приложи скриншот страницы.
Это не значит, что ваш первый файл обязан быть таким подробным. На маленьком проекте хватит трёх пунктов: что за проект, как запускать и проверять, чего не трогать. Остальное допишете, когда вырастет.
Чтобы было видно, ради чего эти двадцать строк, вернёмся к кнопке «Поделиться» и прогоним задачу дважды.
Без файла. Агент начинает с поиска: читает шаблоны темы, потом плагины, потом на всякий случай конфиги. Находит три места, где встречаются похожие кнопки, но не понимает, какое из них актуальное, — и выбирает первое попавшееся. Стили пишет свои, потому что не знает про Sass и правит готовый CSS, который при следующей сборке затрётся. Проверок не запускает, потому что не знает, какие они. Сообщает «готово». Вы открываете страницу и видите кнопку другого размера и цвета, а после первой же пересборки стилей она вообще теряет оформление.
С файлом. Агент читает двадцать строк, видит: шаблоны магазина лежат в конкретной папке, стили правятся только в Sass, кнопки собираются из существующего шаблона, оплату трогать нельзя. Открывает нужную папку сразу, копирует существующий шаблон кнопки, добавляет стиль в Sass, прогоняет сборку и линтер, показывает результат. Разница по времени — минут пятнадцать против часа, но главное не время, а то, что во втором случае результат совпадает с остальным сайтом.
Первый файл проще не писать, а получить
Садиться и сочинять всё это с нуля не обязательно. Быстрее попросить самого агента: «пройдись по проекту, посмотри package.json, composer.json и структуру папок, и собери черновик CLAUDE.md по такому плану» — дальше перечисляете пункты из списка выше.
Агент прочитает конфиги, вытащит реальные команды из скриптов сборки, разложит папки и вернёт заготовку. Дальше ваша работа — вычеркнуть лишнее и дописать то, чего в коде не видно: что трогать нельзя, где лежат чужие интеграции, какие места ломаются чаще всего. Этого в файлах проекта не написано, это знаете только вы.
На вычитку такого черновика уходит минут пятнадцать против часа на сочинение с нуля. Единственное, за чем нужно следить: агент любит писать длинно и торжественно. Всё, что не является командой, путём или запретом, смело режьте.
Одно не стоит смешивать: CLAUDE.md и AGENTS.md — не замена README. README — вход для людей: разработчика, ревьюера, случайного посетителя репозитория. Он объясняет, что за проект и как его поставить. Файлы для агентов лежат рядом и говорят другое: что помнить в каждой сессии, какие команды запускать и каких границ не переходить.
Три уровня правил: общие, проектные и на одну задачу
Проект у вас наверняка не один, и часть правил повторяется во всех: «отвечай по-русски», «не коммить без спроса», «не свети ключи». Копировать их в каждый проектный файл — лишняя работа и риск забыть обновить где-то одно.
Глобальные инструкции верны для всех проектов и всех чатов. Они живут в одном файле, который агент читает везде: у Claude Code это ~/.claude/CLAUDE.md, у Codex — файл в его домашней папке. OpenAI так и советует: личные настройки поведения в глобальный файл, правила команды и кодовой базы — в файлы репозитория.
Мой глобальный файл выглядит примерно так:
# ~/.claude/CLAUDE.md — общие правила для всех проектов
## Как со мной работать
- Отвечай по-русски, коротко, без вступлений и извинений.
- Сначала план на пару строк, потом код. На крупных правках жди «да».
- Предупреждай о рисках до правки, а не после неё.
## Без явного согласия нельзя
- Коммитить, пушить, выкладывать на боевой сервер.
- Удалять файлы, дропать таблицы, чистить кэш на продакшене.
- Обновлять плагины и ядро WordPress.
## Секреты и доступы
- Пароли, ключи и токены не пиши ни в чат, ни в файлы.
- Нужен доступ — скажи, куда его положить, сам ключ мне не показывай.
## Код
- Не тащи новую библиотеку, если задача решается тем, что уже есть.
- Следуй стилю соседних файлов, а не своим предпочтениям.
- Правь минимальный набор файлов, рефакторинг согласуй отдельно.
Проектный файл — всё, что нужно любому агенту, работающему над этим проектом: стек, команды, структура, ограничения, проверки, где искать знания. Это тот самый CLAUDE.md в корне.
Контекст задачи — наоборот, всё сиюминутное: что делаем прямо сейчас, какие файлы уже обсудили, какое ограничение живёт только в этой работе. В CLAUDE.md ему не место, оно устареет завтра. Заведите отдельный файл задачи.
Выглядит файл задачи примерно так — короткий, живёт пару дней и удаляется:
# Задача: ускорить карточку товара
## Что делаем
Карточка грузится 4.2 секунды, цель — уложиться в 2.
Проблема в двух местах: 18 запросов к базе на остатки и несжатые картинки.
## Границы этой задачи
- Оплату и корзину не трогаем вообще.
- Схему базы не меняем, только добавляем индекс и кэш.
- Дизайн не правим, задача чисто про скорость.
## Готово, когда
- Карточка открывается меньше чем за 2 секунды на тестовом сервере.
- Запросов к базе на странице не больше 6.
- `composer lint` и `npm run build` проходят.
Такой файл решает частую беду: агент, увлёкшись, начинает «заодно» чинить всё, что видит. Явно записанные границы задачи держат его в рамках лучше, чем просьба в чате, — потому что чат он забудет при сбросе контекста, а файл прочитает заново.
Тест на то, куда положить правило, простой. «Отвечай по-русски» — глобально, это про вас, а не про проект. «Собирай стили через npm run build» — проектный файл, в другом проекте команда будет своя. «В этой задаче не трогаем оплату» — файл задачи, верно только сегодня. И поверх всех трёх уровней отдельным пунктом: секреты, доступы и приватные адреса не кладём никуда.
Когда один файл начинает мешать
Магазин растёт, и вы дописываете в CLAUDE.md всё подряд: вёрстку, дизайн карточек, SEO, тексты, выкладку, обмен с 1С, правила ревью и ещё пяток договорённостей. Всё в одном месте — вроде удобно.
А потом вы просите поднять SEO карточек, и агент по дороге читает правила вёрстки и инструкцию по выкладке. Просите поправить экран корзины — он тащит в контекст логи, проверки и бизнес-правила. Каждый агент получает весь ворох, хотя нужен ему один кусок.
За раздутый контекст приходится платить точностью. Anthropic называет это context rot: чем больше токенов, тем ниже точность, с которой модель вспоминает нужное. Внимание модели у них описано как бюджет, который тратится с каждым новым токеном.
Ломается это плавно, без обрыва. Длинный файл не отключит агента разом — просто каждый лишний абзац чуть-чуть снижает шанс, что нужное правило вспомнится и сработает. Новые модели держат длинный контекст лучше, но совсем эффект не исчезает.
Обратите внимание, как поменялась проблема. В начале агент не знал о проекте ничего — мы дали ему файл. Теперь он знает слишком много лишнего под конкретную задачу. Это ровно тот случай, про который я писал в разборе про короткий контекст и самопроверку: агенту нужен минимум полезного, а не весь проект целиком.
Корневой файл — указатель, а не энциклопедия
Решение простое: корневой CLAUDE.md остаётся коротким маршрутизатором, а подробные знания уезжают в отдельные файлы по темам — код, вёрстка, данные, выкладка. Работа корневого файла — сказать агенту, куда смотреть, а не пересказать всё самому.
OpenAI формулирует то же правило так: держите главный AGENTS.md коротким, а планирование, ревью и архитектуру выносите в отдельные документы, если файл разрастается. Anthropic называет это прогрессивным раскрытием — индексный файл читается всегда, тематические подтягиваются по необходимости.
В росте это выглядит так. Сначала один CLAUDE.md с базовыми правилами. Потом рядом появляется папка с документами по темам. Потом добавляются файлы задач, чек-листы и автоматические проверки.
Свои плагины на WordPress.org я веду с агентами именно так — AI Thumbnails Maker и SmartyPress AI Engine собраны по одному лекалу. Структура получилась вот такая:
CLAUDE.md / AGENTS.md ← короткий вход, ~35 строк
└── docs/project-knowledge/
├── INDEX.md ← оглавление базы знаний
├── project.md ← что за проект и для кого
├── architecture.md ← стек, структура, схема данных
├── patterns.md ← стандарты кода, git-процесс, тесты
├── deployment.md ← окружения, выкладка, откат
└── ui-guidelines.md ← вёрстка, брейкпоинты, доступность
Само оглавление и есть маршрутизатор. По нему агент решает, какой документ открыть под задачу:
## Когда что читать
- Начинаешь новую фичу — project.md, architecture.md, patterns.md
- Правишь вёрстку или интерфейс — ui-guidelines.md
- Меняешь схему данных или обмен с 1С — architecture.md, раздел «Данные»
- Настраиваешь выкладку или мониторинг — deployment.md
- Заводишь ветку или пул-реквест — patterns.md, раздел «Git»
Пришла задача про интерфейс — агент открывает только гайд по вёрстке. Задача про выкладку — только документ про выкладку. Ни схема данных, ни git-процесс в контекст при этом не тащатся.
Вернёмся к магазину — он к этому моменту вырос так же. Минимальный файл превратился в короткий вход плюс тематические документы, и внутри уже лежит конкретика. Вот его architecture.md:
# Архитектура — магазин на WooCommerce
## Стек
- WordPress 6.x + WooCommerce — витрина, каталог, заказы.
- PHP 8.2, MySQL 8.
- Дочерняя тема — вся вёрстка. Родительскую не трогаем.
- Плагин shop-integration — обмен с 1С и приём платежей.
- Sass → CSS через `npm run build`, исходники в `assets/scss`.
## Где что лежит
- `themes/shop-child/woocommerce/` — переопределённые шаблоны магазина.
- `themes/shop-child/inc/` — хуки, фильтры, регистрация сущностей.
- `plugins/shop-integration/src/` — обмен, платежи, очереди.
## Данные
- Заказы и товары — штатные таблицы WooCommerce, своих не заводим.
- Остатки приходят из 1С раз в час и пишутся в мету товара `_stock`.
- Журнал обмена — таблица `wp_shop_sync_log`, чистится раз в 30 дней.
## Важные места
- `src/Payment/` — приём платежей. Менять только по согласованию.
- `woocommerce/checkout/` — оформление заказа, ломается заметнее всего.
Переносить к себе стоит не конкретные технологии, а сами заголовки: «Стек», «Где что лежит», «Данные», «Важные места». Это скелет, который вы заполните своим.
Чего в файл класть не надо
Половина работы над таким файлом — это вычёркивание. Вот что я убираю в первую очередь, когда мне присылают разбухший CLAUDE.md.
Пересказ того, что агент и так видит. Список всех файлов проекта, содержимое package.json, перечень установленных плагинов. Агент прочитает это сам за одну команду, а в контексте оно лежит постоянно.
Историю проекта и обоснования. «Изначально мы использовали X, но потом перешли на Y, потому что…» — интересно человеку, бесполезно агенту. Ему нужно текущее состояние, а не путь к нему.
Правила, которые уже проверяет автоматика. Отступы, кавычки, порядок импортов. Это работа линтера, и дублировать её текстом — только жечь контекст.
Вежливые формулы. «Пожалуйста, постарайся», «было бы здорово, если бы». Агент не обидится на сухой императив, а каждое лишнее слово занимает место.
Всё, что устаревает быстрее, чем вы успеваете править. Номера версий с точностью до патча, имена людей в команде, сроки. Через месяц это будет враньё, а агент поверит написанному.
Подпроект — свой файл рядом с ним
Бывает, что под одной крышей живёт несколько проектов: сайт, админка, бот, инфраструктура. Корневой файл описывает общие правила, но внутри каждой части могут быть свои команды, свой стек и свои ограничения.
Тогда рядом с подпроектом кладут отдельный файл правил. Инструменты это поддерживают. Claude Code читает CLAUDE.md, начиная от папки, где идёт работа, и поднимаясь к корню, а файл во вложенной папке подхватывает, только когда агент туда заходит. Codex собирает инструкции от корня до текущей папки, и ближний файл перекрывает дальний.
У меня так устроен проект, где рядом живут сайт на WordPress и админский сервис на Laravel. В корне лежат общие правила: как отвечать, что не коммитить, где база знаний. А внутри каждой части — свой файл, потому что команды там разные: в одной половине composer и wp-cli, в другой artisan и другой набор тестов. Общее правило «прогоняй линтер перед сдачей» живёт в корне, а конкретная команда линтера — в файле подпроекта, каждая своя.
Вложенный файл нужен, если внутри этой части действительно другие команды, стек, ограничения или проверки. Не нужен, если правило одинаково для всего проекта. Худший вариант — размножить одну и ту же копипасту по всем папкам: правило поменялось, а вы уже не помните, в каком из пяти файлов его обновлять, и они начинают тихо расходиться.
Переписывайте пожелания в выполнимые правила
Большая часть бесполезных строк в таких файлах — моральные советы, которые агент игнорирует, потому что не понимает, что конкретно делать. Лечится переводом пожелания в действие, запрет, проверку или ссылку на документ.
Формулировки ниже — из ошибок, которые у меня повторялись. Слева то, как хочется написать, справа — то, что агент сможет выполнить:
- «Пиши чистый код» → «перед созданием новой функции поищи существующую по проекту и переиспользуй — либо объясни, почему делаешь новую».
- «Не раздувай решение» → «меняй минимальный набор файлов, отдельный рефакторинг согласуй до правок».
- «Не ломай проект» → «перед сдачей прогони composer lint и npm run build и напиши, что прошло».
- «Аккуратнее с базой» → «любой запрос, меняющий данные, сначала покажи мне текстом, потом выполняй».
Ещё несколько из той же серии, уже ближе к WordPress:
- «Соблюдай стандарты WordPress» → «перед сдачей прогони composer lint, вывод должен быть пустым».
- «Не ломай вёрстку на мобильных» → «проверь страницу на ширине 375 и 768 пикселей, приложи два скриншота».
- «Осторожнее с плагинами» → «новые плагины не устанавливай, задачу решай средствами темы и существующих плагинов».
- «Пиши понятные коммиты» → «сообщение коммита: что изменилось и в каком модуле, одной строкой на русском».
Слева — оценка, которую агент не может проверить на себе. Справа — конкретное действие с понятным результатом. «Пиши чистый код» каждый понимает по-своему. «Поищи существующую функцию и переиспользуй» проверяемо: либо искал, либо нет.
Отсюда критерий хорошего правила. Оно задаёт одно из пяти: действие, запрет, проверку, критерий готовности или ссылку на конкретный документ. Всё остальное — благие пожелания, которые звучат разумно и не работают.
Критичное выносите в автоматические проверки
Есть правила слишком важные, чтобы держать их одной строкой в тексте. Возьмём «не пиши секреты». Строчка в файле — это надежда, что агент вспомнит её в нужный момент. Особенно шаткая, если файл длинный.
OpenAI советует ровно это: не полагаться на текст, а подпереть его автоматикой, которая правила не просит соблюдать, а принуждает. Это программы, проверяющие каждое изменение — прогоняют тесты, сверяют стиль кода, ищут утёкшие ключи — и не пускают дальше то, что не прошло.
Инструментов несколько, каждый закрывает свой участок. Хуки — маленькие программы, срабатывающие в нужный момент: например, перехватывают опасную команду до того, как агент её выполнит. Проверки при сохранении изменений ловят случайно попавшие в код пароли. CI независимо собирает проект и гоняет тесты перед тем, как изменения принять. Помнить названия не нужно — агент настроит их сам, если попросить.
Самый полезный из них в моей работе — перехват опасных команд. Правило «не удаляй файлы без спроса» в тексте агент нарушал примерно раз в месяц: увлекался уборкой и сносил что-нибудь нужное. Хук, который просто не даёт выполнить rm -rf и прямые запросы на удаление в базе, закрыл вопрос совсем — теперь агент упирается в стену и спрашивает, вместо того чтобы вспоминать строчку из файла.
Работает это грубо и надёжно: список запрещённых шаблонов команд, и если очередная команда под шаблон попала — она не выполняется, а агент получает сообщение, что так нельзя. Никакой интерпретации, никакой доброй воли.
Одну ошибку тут делают часто: дублируют в инструкции то, что и так ловит линтер. В исследовании реальных AGENTS.md такое повторение оказалось самой частой проблемой — его нашли в 62% файлов выборки. Если проверку делает автоматика, правило в тексте лишнее: оно только раздувает файл и роняет ту самую точность, ради которой мы контекст и подрезаем.
| Желание в инструкции | Надёжная опора | Что ловит |
|---|---|---|
| Не коммить секреты | сканер секретов в pre-commit | ключи и пароли в изменениях |
| Не ломай сборку | сборка и линтер в CI | проект собирается, стиль соблюдён |
| Пиши тесты | критерий готовности + прогон тестов | рабочие сценарии остались рабочими |
| Не сломай соседний модуль | тесты и ревью | поломку договорённости между частями |
| Докажи, что готово | финальный ответ с командами и логом | быстрый след проверки для человека |
Автоматика ловит только механические ошибки: что проект собирается, ключ не утёк, тесты зелёные. Архитектурные решения и продуктовые риски она не поймает — их всё равно смотрит человек. Смысл проверок в том, чтобы снять с него рутину.
Обновляйте файл после ошибок, а не по расписанию
Сгенерированный на старте файл — это гипотеза о проекте. Полезным он становится, когда вы дописываете в него то, на чём агент реально споткнулся.
Дальше всё идёт по кругу: агент ошибся → называем тип сбоя → выбираем слой для исправления → проверяем, что ошибка не повторяется. OpenAI описывает тот же цикл: обновляйте файл, когда агент повторяет ошибку, читает лишние документы или снова ловит один и тот же комментарий на ревью.
Есть простое правило, когда вообще садиться за правку: ошибка должна повториться дважды. Первый раз — случайность, агент мог просто неудачно понять формулировку задачи. Второй раз — уже система, и вот тогда её стоит закрывать правилом. Иначе файл распухает от реакций на разовые промахи, каждая из которых сама по себе разумна, а вместе они дают ту самую свалку.
Ключевое — выбрать правильный слой. По привычке всё летит в корневой файл, и это зря. Один и тот же сбой лечится в разных местах:
| Сбой агента | Что менять |
|---|---|
| Написал новую функцию вместо существующей | правило поиска в проектном файле и ссылка на архитектуру |
| Раздул решение | правило минимальных правок и согласование рефакторинга |
| Полез искать логи опасным путём | отдельный документ с безопасным маршрутом |
| Не прогнал проверки | критерий готовности и CI |
| Ошибается только в одном модуле | локальный файл правил рядом с этим модулем |
| Один и тот же спор на ревью | обновить чек-лист задачи или правило приёмки |
Пример из моей практики с плагином Unnotifier. Агент раз за разом лез искать логи ошибок по всему серверу и находил не те. Первым порывом было дописать в корневой файл «смотри логи аккуратно» — бесполезная строчка. Правильным решением оказался отдельный документ с точным путём к нужному файлу и командой для его чтения, а в корневом файле — одна ссылка на него. Повторяющаяся боль ушла и перестала переписываться в промпт заново каждый раз.
Чтобы это не держалось на силе воли, обновление стоит встроить в процесс. У меня есть команда, которая по завершении задачи заставляет агента перечитать, что менялось, обновить затронутые документы базы знаний и закоммитить их отдельно. Знание фиксируется в момент завершения работы, а не «когда-нибудь потом». Про сам принцип — что агент устроен как цикл с самопроверкой — я писал в разборе про устройство агентов; фиксация ошибок как раз замыкает этот цикл на уровне проекта.
Как понять, что файл вообще работает
Отдельная беда: файл написан, лежит в корне, а поведение агента не изменилось. Проверить это можно за минуту.
Самое простое — спросить напрямую: «какие правила проекта ты сейчас видишь, перечисли по пунктам». Если в ответ приходит пересказ вашего файла, он прочитан. Если общие слова про хороший код — не прочитан, и дальше надо разбираться с расположением и именем файла.
Второй способ — дать заведомо проверяемое поручение. Например, попросить сделать мелкую правку и посмотреть, прогонит ли агент в конце команды проверок, которые вы прописали. Прогнал и отчитался — правило работает. Сказал «готово» без единой команды — правило написано так, что его удобно проигнорировать: скорее всего, оно сформулировано как пожелание, а не как критерий приёмки.
Третий — самый показательный. Возьмите ошибку, из-за которой вы правило и добавили, и воспроизведите условия. Агент повторил её — правило не сработало, и лечить надо не текст, а слой: перенести в автоматическую проверку или в отдельный документ, который читается именно под такую задачу.
Чек-лист: проверьте свой файл
Пройдитесь по своему CLAUDE.md, AGENTS.md или правилам Cursor и честно ответьте:
- Понятно ли, какой агент читает этот файл?
- Отделены ли ваши личные привычки от правил проекта?
- Есть ли базовый курс молодого бойца: команды запуска, проверок и критерий готовности?
- Не разросся ли корневой файл в свалку обо всём?
- Есть ли маршруты к тематическим документам вместо пересказа их содержимого?
- Понятно ли из ссылок, когда именно эти документы читать?
- Нет ли в файле секретов, доступов и опасных команд?
- Конкретны ли правила и проверяемы ли они? Критичное подпёрто хуком, тестом или CI?
- Не противоречат ли друг другу разные файлы правил?
- Понятно ли, что обновлять после повторяющейся ошибки?
И маршрут на сегодня, если файла ещё нет или он давно превратился в свалку. Создайте файл под свой инструмент. Напишите минимальный курс молодого бойца: стек, команды, карта папок, критерий готовности. Отделите глобальные привычки от проектных правил. Если файл уже пухнет — вынесите тематические знания в отдельные документы, а в корне оставьте маршруты к ним. И закрепите одну повторяющуюся ошибку правилом прямо сегодня.
Отдельно проверьте, не спорят ли правила между собой. Это самая неприятная поломка: в глобальном файле написано «не коммить без спроса», а в проектном кто-то дописал «коммить после каждой правки». Агент выберет одно из двух, и предсказать какое — невозможно. Противоречия чаще всего появляются, когда файл правят несколько человек или когда проектный файл скопировали с другого проекта и не вычитали. Разбирается это просто: при любом сомнении читаете оба файла подряд, как читал бы их агент, и убираете то, что мешает.
Работают такие файлы ровно до тех пор, пока они короткие, конкретные, проверяемые и вы поддерживаете их после реальных ошибок. Сгенерировали на старте и забыли — через месяц получите такой же шум, от которого уходили. Мой ориентир простой: если корневой файл перестал помещаться на один экран, значит, пора выносить половину в отдельные документы.
