Что пишут в CLAUDE.md и AGENTS.md: разбор 3 126 популярных репозиториев GitHub

К сожаленью, не нашел в русскоязычном комьюнити расширенного писания правил, как сейчас складывается практика по CLAUDE.md или AGENTS.md, хотя за более чем год она должна была сложиться. Поэтому решил провести свое исследование, чтобы можно было говорить не на уровне персональной экпертности, а на уровне цифр и того, как эти подходы помогают продвигать продукты.

Файл правил для AI‑агента — CLAUDE.md или AGENTS.md в корне репозитория — сейчас пишут почти все, кто работает с агентами всерьёз. Советов, что туда класть, много, и почти все они — личный опыт. Мне захотелось посмотреть на практику: что реально лежит в популярных репозиториях.

Я собрал четыре выборки по 1 000 проектов, прогнал по ним 70 шаблонов правил и свёл результат в 20 базовых правил. А потом взял проект с самым высоким покрытием — garrytan/gstack — и прочитал его файлы глазами. Вторая часть оказалась полезнее первой: она показала, где мой собственный метод врёт.

Сбор и подсчёт я делал вместе с агентом (Claude Code): он писал и запускал скрипты, я ставил задачи и перепроверял. Об этом тоже расскажу.

Коротко:

• AGENTS.md есть у 18% просмотренных популярных репозиториев, CLAUDE.md — у 12%. Почти в половине случаев CLAUDE.md — это ссылка на AGENTS.md.

• Медианный файл — около 6 000 символов, 90–120 строк.

• Наверху рейтинга не запреты, а справка: команды, проверки, устройство проекта.

• Заглавные IMPORTANT / NEVER / MUST есть в четверти файлов; у медианного файла их ноль.

• В проектах моложе полугода заметно меньше правил про линтер, стиль и тесты и больше — про поведение самого агента.

• Подсчёт регулярными выражениями завышает покрытие. На единственном файле, который я проверил вручную, из 18 «найденных» правил как минимум три, по сути, отсутствуют.

Как собирались данные

Отбор репозиториев

Источник — поиск репозиториев через GitHub GraphQL API с сортировкой по звёздам. Признаком «проект пишется с участием агента» я принял наличие файла правил: напрямую на GitHub это не определить.

Удобство GraphQL в том, что за один запрос можно получить и метаданные репозитория, и содержимое файлов по выражению HEAD:путь:

query($q: String!, $after: String) {  search(query: $q, type: REPOSITORY, first: 50, after: $after) {    pageInfo { hasNextPage endCursor }    nodes {      ... on Repository {        nameWithOwner stargazerCount isFork isArchived createdAt        primaryLanguage { name }        claude:    object(expression: "HEAD:CLAUDE.md")         { ... on Blob { text } }        dotclaude: object(expression: "HEAD:.claude/CLAUDE.md") { ... on Blob { text } }        agents:    object(expression: "HEAD:AGENTS.md")         { ... on Blob { text } }      }    }  }}

Поиск GitHub отдаёт не больше 1 000 результатов на запрос, поэтому скрипт идёт «срезами» по звёздам: первый запрос stars:>1000 sort:stars-desc, после исчерпания тысячи — stars:<=N, где N — число звёзд последнего увиденного репозитория. Дубликаты на границах отсекаются по имени. Проход останавливается, когда набрана тысяча репозиториев с нужным файлом.

Детали отбора:

• CLAUDE.md искался в корне и в .claude/, AGENTS.md — только в корне. Вложенные файлы в подкаталогах не учитывались.

• «Популярность» — число звёзд на момент сбора, других критериев нет.

• Форков в выборках нет: поиск не возвращает их по умолчанию.

• Общие выборки собраны 7–8 октября 2 026 года, выборки новых проектов — 13 октября. «Новые» — созданные с 13 апреля 2 026 года (запрос с created:>=2026-04-13).

Четыре выборки

Выборки пересекаются, и это важно для интерпретации:

Уникальных проектов во всех четырёх — 3 126, а не 4 000.

Проекты с обоими файлами

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

Как считались правила

Регулярными выражениями, без LLM. Я просмотрел заголовки и императивные строки первых двух сотен файлов, составил список из 70 типовых правил и на каждое написал шаблон. Правило засчитывается проекту, если шаблон сработал в тексте хотя бы раз.

Пример шаблона для правила «не коммитить и не пушить без явной просьбы» (список отрицаний здесь сокращён):

const NEG = "(?:never|do not|don't|dont|avoid|must not|should not)";new RegExp(  `${NEG}[^\\n]{0,25}\\b(commit|push)\\b[^\\n]{0,50}` +  `(unless|without|explicit|ask|permission|request|instruct|approv)` +  `|only commit when|ask before (commit|push)`, 'i')

У метода есть очевидные слабости, и я к ним вернусь отдельно:

• Список правил составлен мной вручную, это не кластеризация.

• Точность шаблонов не проверялась на размеченной выборке.

• Часть шаблонов ловит упоминание темы, а не правило: «безопасность», «производительность», «CI».

• Шаблоны в основном английские; файлы на других языках посчитаны хуже.

Что получилось

Форма файла

Медианный размер текста правил — от 5 900 до 6 400 символов в зависимости от выборки, это 90–120 строк. Девяностый перцентиль — около 24 000 символов.

Как соотносятся два файла (общие выборки):

Направление ссылок одностороннее: правила пишут в AGENTS.md, а CLAUDE.md на него указывает. Обратное встречается на порядок реже.

Рейтинг правил

Доля проектов, где правило встречается хотя бы раз.

Наблюдения

Файл правил — справочник, а не свод запретов. Верх рейтинга занимают команды, проверки и устройство проекта. Первое поведенческое правило («сначала прочитай код») появляется только на десятом‑двенадцатом месте.

Жёстких запретов мало. Запрет force‑push — около 5%, «не коммить без просьбы» — около 5%, запрет разрушающих команд — 9–14%. Если объединить всё про необратимые действия в одно правило, получится 15–19% проектов.

Капс используют умеренно. Он есть в четверти файлов старых проектов и в 10–14% новых; у медианного файла заглавных IMPORTANT/NEVER/MUST нет вообще.

AGENTS.md больше про процесс, CLAUDE.md — про устройство и инструменты. В AGENTS.md чаще встречаются правила PR (66,7% против 57,3%) и тесты на изменения (44,1% против 38,1%). В CLAUDE.md — описание архитектуры (51,0% против 35,9%), MCP и субагенты.

Новые проекты пишут другое. Требований к инженерной дисциплине меньше: линтер 76% → 55%, стиль кода 52% → 33%, тесты на изменения 38% → 23% (цифры по CLAUDE.md). Правил про самого агента больше: skills 23% → 34%, проверка результата 21% → 28%, запрет разрушающих команд 9% → 12%. Раскрытие использования ИИ почти исчезает: 3,9% → 1,2%.

Это наблюдение, а не причинный вывод. Новые проекты в выборке в двадцать раз меньше по звёздам, у них меньше контрибьюторов и формальных стандартов. Разделить эффект возраста и эффект масштаба на этих данных нельзя.

Что из 70 правил дублирует друг друга

Часть правил всегда ходит вместе. Я посчитал вложенность: какая доля проектов с более редким правилом содержит и более частое.

• Conventional Commits входит в «формат сообщений коммитов» на 100% — частный случай.

• Проверка типов, «запускай проверки перед завершением» и «не обходи хуки» в 93–95% случаев идут вместе с требованием линтера.

• «Как запустить один тест» в 92% случаев стоит рядом с командами тестов.

• Ссылка на второй файл и импорты через @path — 91%.

После объединения близких по смыслу получилось 20 базовых правил. Объединение ручное; численно подтверждены только перечисленные пары.

Двадцать базовых правил

Доля — проекты, где встречается хотя бы одно правило из объединения; среднее и диапазон по четырём выборкам.

Правила 1–5 нельзя скопировать из чужого проекта: это слоты, которые заполняются под свой репозиторий. Правила 7, 12, 13, 14, 18 переносятся почти дословно. Самые устойчивые по выборкам — 7, 17 и 18: разброс в пределах пяти пунктов.

Разбор примера: garrytan/gstack

Чтобы посмотреть на правила не в агрегате, а в тексте, я искал проект, где содержательны оба файла и покрыто не меньше 90% базовых правил.

Пар «оба файла не короче 1 500 символов, ни один не ссылка» в данных 295, из них англоязычных и неидентичных — 210. Порог 18 из 20 проходит один проект. Ещё пять набирают 17, четыре — 16, а основная масса — от 8 до 14. Все двадцать не покрывает никто.

Этот один проект — garrytan/gstack: набор навыков и слэш‑команд для Claude Code от Гарри Тана, около 136 тысяч звёзд, создан в марте 2 026 года. Пример нетипичный: это инструментарий для агента, и его правила описывают разработку самого инструментария. Файлы большие: CLAUDE.md — 614 строк, AGENTS.md — 299 строк, при медиане по выборке около 110.

Ссылки:

• проект: github.com/garrytan/gstack, лицензия MIT;

• оригинал CLAUDE.md;

• оригинал AGENTS.md.

Файлы меняются почти каждый день, поэтому ссылки на конкретные строки ниже зафиксированы на коммите 953a62a от 13 октября 2 026 года.

Примеры ниже — схемы и пересказ: имена команд, навыков и полей приведены как в оригинале, пояснения мои. Дословный текст каждого раздела открывается по ссылке на строки.

Как разделены файлы

AGENTS.md — входная точка для любых агентов: каталог из более чем пятидесяти навыков в семи таблицах, общий порядок проверки работы, команды сборки, поддержка платформ. CLAUDE.md — подробные правила разработки самого проекта, 28 разделов. Файлы ссылаются друг на друга: CLAUDE.md отсылает к разделу о проверке в AGENTS.md, тот — к разделу об оценках в CLAUDE.md. Дублируются только команды сборки.

Примеры из файлов с комментариями

У каждого примера указано, какому базовому правилу он соответствует — и насколько. Эти пометки я потом перепроверял по тексту; результат проверки в следующем разделе.

1. Команды с ценой запуска

Источник: CLAUDE.md, Commands и AGENTS.md, Build commands.

bun run typecheck        строгая проверка типов, допускается ноль ошибокbun run test:quick       быстрый бесплатный срез для обратной связи, не приёмкаbun run test             полный бесплатный наборbun run eval:bg:pr       платные проверки только по изменённомуbun run eval:bg:release  полный платный прогон

Комментарий. Что это: список команд сборки и тестов с пометками о стоимости. Зачем: агент знает, чем проверять и какие запуски тратят деньги на API. Базовое правило № 1 «Команды: сборка, запуск, тесты, один тест, менеджер пакетов» — соответствует. Пометка о цене в выборке почти не встречается, а для агента, способного запустить платную оценку в цикле, она важнее самой команды.

2. Сгенерированные файлы

Источник: CLAUDE.md, SKILL.md workflow.

1. править шаблон          SKILL.md.tmpl2. перегенерировать        bun run gen:skill-docs3. закоммитить оба файла   шаблон и сгенерированный SKILL.mdконфликт слияния в SKILL.md → решать в шаблоне, затем шаг 2

Комментарий. Что это: порядок работы со сгенерированными файлами навыков. Зачем: правки вносятся в шаблон, а не в результат генерации, иначе они потеряются. Отдельно оговорено, что при конфликте нельзя принимать одну из сторон в сгенерированном файле: изменения второй стороны молча пропадут. Базовое правило № 20 «Не править сгенерированные и вендорные файлы» — соответствует.

3. Файл правил как хранилище настроек

Источник: CLAUDE.md, Platform‑agnostic design.

нужна команда тестов, деплоя или оценки├─ есть в CLAUDE.md проекта → взять оттуда└─ нет → спросить пользователя → записать ответ в CLAUDE.md

Комментарий. Что это: требование не зашивать в навыки команды конкретного фреймворка. Зачем: навыки должны работать в любом проекте. Интересен побочный эффект: CLAUDE.md используется не только как инструкция, но и как место, куда агент сам дописывает настройки проекта. Прямого соответствия базовым правилам нет.

4. Протокол вины

Источник: CLAUDE.md, E2E eval failure blame protocol.

сквозная проверка упала на ветке├─ на main тоже падает       → «было до нас», с приложенным доказательством├─ на main проходит          → причина в наших изменениях, искать└─ на main запустить нельзя  → «не проверено», вынести в риски в описании PR

Комментарий. Что это: порядок действий при упавшей сквозной проверке. Зачем: нельзя объявлять сбой чужим, не доказав это запуском на основной ветке. Формулировка в файле короткая: «Prove it or don’t say it». Базовое правило № 12 «Проверяй результат и чини причину» — соответствует.

5. Число попыток фиксируется до запуска

Источник: AGENTS.md, Validation discipline.

Комментарий. Что это: фрагмент девяти шагов исправления сбоев и подготовки выпуска. Зачем: сначала диагноз, потом точечная проверка, в конце один полный прогон на замороженном коде. Запрещено добавлять попытки после того, как увиден результат, снижать пороги и пропускать случаи. Базовые правила № 2 «Прогоняй проверки: линтер, типы, перед завершением, не обходи хуки» — частично: обязательные проверки и финальный прогон есть, про линтер и хуки ничего нет; № 12 «Проверяй результат и чини причину» — соответствует.

6. Гигиена коммитов

Источник: CLAUDE.md, Commit style и Compiled binaries.

git add src/parser.ts test/parser.test.ts   # так: конкретные файлыgit add .                                   # так нельзя: захватит сборку и мусор

Имена файлов в примере условные.

Комментарий. Что это: правило «один коммит на одно логическое изменение» и запрет добавлять в индекс всё рабочее дерево. Зачем: переименование отделяется от изменения поведения, шаблоны — от сгенерированных файлов; историю легче читать и откатывать. Базовое правило № 3 «Коммиты, ветки, PR» — частично: только про коммиты; про ветки, формат сообщений и PR здесь ничего нет.

7. Делегирование с границей

Источник: CLAUDE.md, CHANGELOG + VERSION style.

номер версии          агент выбирает сам, владельца не спрашиваетпо умолчанию          PATCH**Choose versions autonomously; default to PATCH.** Garry delegates releaseversion decisions to the agent. Do not ask him to choose or approve a version,including when an already-approved version collides with another PR. This policyoverrides generic version-approval prompts in `/ship` and `/document-release`.MINOR или MAJOR       только если назвать выпуск патчем было бы явной неправдойPrefer **PATCH (X.Y.Z+1.0)** for ordinary releases, including fixes, additions,refactors, test infrastructure and coordinated multi-file work. Diff size aloneis not a reason to choose MINOR. Choose **MINOR (X.Y+1.0.0)** or **MAJOR(X+1.0.0.0)** only when calling the release a patch would be plainly misleading("ridiculous"), such as an incompatible public-interface change or a genuinelynew product-scale release. Make that judgment without another approval question.это не разрешает      сливать, деплоить, пропускать обязательные проверкиUse `bin/gstack-next-version` to check the live release queue before publishing.If a slot is claimed, advance to the next available version at the chosen bumplevel and use `bin/gstack-version-bump` to synchronize release metadata. A higherbase version does not itself require a MINOR bump. Keep the PR ready for Garry tomerge; autonomous version decisions do not authorize merging, deploying orskipping required validation.**VERSION and CHANGELOG are branch-scoped.** Each shipping branch gets its ownbump and one entry, written at `/ship` time, that describes what THIS branchadds versus main, for users, with no branch-internal versions or developmentnarrative. VERSION stays 4-digit; package.json carries the 3-digit npmtranslation owned by `bin/gstack-version-bump`, so never hand-edit it. Read[docs/CHANGELOG_STYLE.md](docs/CHANGELOG_STYLE.md) BEFORE writing an entry: itholds the versioning invariant, the merge-main checks, what stays out and theentry format. Always credit community contributions with`Contributed by @username`.

Комментарий. Что это: как выбирать номер версии и писать запись об изменениях. Зачем: снять с человека рутинное решение и при этом явно ограничить, что из него не следует. Базовое правило № 8 «Совместимость и сопровождение: breaking changes, changelog, документация» — соответствует.

8. Маршрутизация по навыкам

Источник: CLAUDE.md, Skill routing.

Комментарий. Что это: таблица «тип запроса — какой навык вызвать»; здесь приведена часть строк. Зачем: агент выбирает подходящую роль сам, без подсказки пользователя. Базовое правило № 6 «Инструменты агента: skills, субагенты, MCP» — соответствует.

9. Журнал решений между сессиями

Источник: CLAUDE.md, Cross‑session decision memory.

{  "decision": "храним суммы в целых копейках",  "rationale": "ошибки округления в отчётах",  "scope": "repo",  "source": "user",  "confidence": 9}

Имена полей — как в оригинале, значения условные.

Комментарий. Что это: журнал долговременных решений с обоснованиями, в который можно только дописывать. Зачем: не пересматривать уже принятое и не терять причины между сессиями. В файле определено, что считается долговременным (выбор архитектуры, отказ от части объёма, выбор инструмента) и что нет (правка формулировки, разовое изменение). Прямого соответствия базовым правилам нет; ближе всего правило из группы «память агента», которое в выборке встречается у 6–12% проектов.

10. Навыки‑ограничители

Источник: AGENTS.md, Safety + scoping.

Комментарий. Что это: таблица навыков‑ограничителей, которые включает пользователь; в ней же стоят не связанные с безопасностью /make-pdf и /diagram. Зачем: предупреждать перед разрушающими командами и запрещать правки вне выбранного каталога. К базовому правилу № 18 «Необратимое только с разрешения» относится лишь отдалённо: это подключаемые инструменты, а не постоянное правило для агента.

Где он расходится с трендом выборки

• Объём. Правило 13 в выборке — «не делай лишнего». В gstack установка обратная: делать полную реализацию, а не короткий путь.

• Необратимые команды. В инструкции по развёртыванию git reset --hard указан как обычный шаг, без оговорок о подтверждении.

• Капс. NEVER и MUST используются в нескольких местах, хотя у медианного файла их нет.

• Размер. CLAUDE.md в пять с лишним раз больше медианы.

Где врёт метод

По регулярным выражениям gstack покрывает 18 базовых правил из 20. Я разметил разделы обоих файлов вручную — к какому базовому правилу относится каждый — и потом перечитал текст, проверяя собственную разметку. Из 17 привязок:

• 10 соответствуют по сути;

• 3 соответствуют частично;

• 4 не соответствуют.

Что именно не сошлось:

Частичные совпадения того же рода: правило «коммиты, ветки, PR» засчитано, хотя в разделе только про коммиты; «прогоняй проверки» — хотя про линтер и хуки нет ни слова.

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

Ограничения

• Частота не равна эффективности. Я измерял, что принято писать, а не что улучшает работу агента.

• Список правил и группировка — ручные. Другой автор разбил бы иначе.

• Только корневые файлы. У крупных проектов правила часто вынесены во вложенные файлы. Пример из той же выборки — PhotoPrism: его корневые файлы работают как оглавление к девяти вложенным AGENTS.md и каталогу .claude/rules/, и мой подсчёт всего этого не видит.

• Английский язык. Файлы на других языках недосчитаны.

• Выборки пересекаются и различаются по масштабу проектов.

• Поиск GitHub неполон. Часть запросов вернула неполные страницы или ошибку, отдельные репозитории могли выпасть.

• Наличие файла — косвенный признак. Файл правил может лежать в репозитории, которым агенты почти не пользуются.

Практические выводы

Начинайте со справки, а не с запретов. Команды, обязательные проверки, карта каталогов — то, что есть у большинства и что агент иначе будет угадывать.

Держите один источник. Если в проекте работают разные агенты, пишите правила в AGENTS.md, а в CLAUDE.md оставьте импорт и то, что относится только к Claude Code:

@AGENTS.md# Дополнения для Claude Code…skills, субагенты, MCP

Разведите правила, которые конфликтуют. В реальных файлах рядом стоят «прогоняй все проверки» и «запускай точечно», «минимальные правки» и «пиши тесты», «спрашивай» и «не останавливайся». Агенту нужен критерий, а не оба лозунга: например, «во время работы — тесты затронутых файлов, перед сообщением о готовности — полный прогон».

Пометьте цену и необратимость. Какие команды платные, какие нельзя запускать без подтверждения. Это редкие правила в выборке, но именно их агент не выведет из кода.

Не раздувайте. Медиана — около ста строк. Если правил больше, выносите их во вложенные файлы по каталогам, как делают крупные проекты.

Комментарии для людей в CLAUDE.md бесплатны. По документации Claude Code, блочные HTML‑комментарии вырезаются из CLAUDE.md перед загрузкой в контекст модели. Там можно оставлять пояснения для мейнтейнеров. На AGENTS.md и других агентов это не распространяется: они читают файл как есть.

Минимальный каркас, собранный из самых частых правил:

# <Проект>## Команды- Установка / сборка / запуск: `<…>`- Все тесты: `<…>`; один тест: `<…>`- Линтер, проверка типов: `<…>`## Проверки- Во время работы — тесты затронутых файлов; перед сообщением о готовности — всё целиком.- Не обходи хуки и не отключай проверки, чтобы они прошли.- О результате сообщай по выводу команд.## Устройство проекта- `<каталог>/` — <назначение>- Сгенерированные файлы (`<путь>`) вручную не правятся.## Перед правкой- Прочитай изменяемый код и места вызова.- Если трактовки ведут к разному результату — спроси.## Объём изменений- Меняй только то, что нужно для задачи.- Сначала ищи существующее решение в коде проекта.## Git- Формат коммитов: <…>- Коммит и push — только по явной просьбе.- Без force-push, `reset --hard` и удаления файлов вне задачи без разрешения.## Подводные камни- <то, на чём уже ошибались>

Про работу с агентом

Всё описанное сделано за несколько сессий диалога с Claude Code: доступ к GitHub шёл через навык Agent Reach и gh, скрипты сбора и подсчёта — на Node.js. Агент писал код, запускал его, возобновлял сбор после сбоев API и пересчитывал выборки, когда я менял условия.

Самое ценное в этом процессе произошло в конце. Я попросил проверить, соответствуют ли привязки правил тексту файлов «по сути» и ничего не придумывать, — и получил список из четырёх привязок, которые не соответствуют, и трёх неточностей в описаниях, сделанных самим же агентом до этого. Без этого шага в статье стояло бы «18 из 20» как факт.

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

Если у вас есть размеченные данные по файлам правил или идеи, как оценить точность шаблонов без ручной разметки, — буду рад обсудить в комментариях.