CLAUDE.md: файл, который улучшает агентов кодирования

Хороший CLAUDE.md не делает модель умнее. Он делает задачу менее неоднозначной каждый раз, когда агент входит в ваш репозиторий.

Этот скромный механизм объясняет, почему репозиторий, построенный вокруг четырёх простых правил, стал одним из самых заметных проектов агентов в 2026 году. Инструкции велят агенту высказывать предположения, предпочитать простые реализации, делать хирургические изменения и определять проверяемый успех. Ничего из этого не ново в software engineering. Полезная часть — держать все четыре в контексте перед каждой задачей.

Вирусный заголовок говорил, что один файл получил 91 000 звёзд на GitHub. К 2 августа 2026 года репозиторий перешёл из forrestchang в multica-ai, вырос в плагины и правила редакторов и достиг 198 529 звёзд по данным GitHub API.^[1] Число будет меняться. Неизменный урок: как небольшие, стойкие инструкции меняют поведение агента.

TL;DR

• CLAUDE.md — это файл Markdown с постоянными инструкциями, которые Claude Code загружает как контекст.^[2]
• Вирусный репозиторий свёл типичные ошибки агентов к четырём правилам: думай перед кодированием, простота прежде всего, хирургические изменения и целеустремлённое выполнение.^[3]
• Файл лучше всего работает, когда содержит факты и правила, нужные почти в каждой сессии: команды, архитектуру, соглашения, границы и проверку.
• CLAUDE.md — это контекст, не обязательное правило. Используйте разрешения и hooks для действий, которые должны быть технически заблокированы.^[2]
• Храните процедуры, специфичные для задачи, в skills и указания, специфичные для файла, в .claude/rules/; загрузка всего глобально тратит контекст впустую.
• Полезный файл достаточно короток для поддержки, достаточно конкретен для тестирования и пересматривается каждый раз, когда агент повторяет ошибку.

Что такое CLAUDE.md?

CLAUDE.md — это файл инструкций проекта Claude Code. Это обычный Markdown, обычно закомичен в корень репозитория и даёт агенту стойкий контекст вроде:

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

Claude Code читает файл в начале сессии. Anthropic описывает его как один из двух механизмов памяти: люди пишут инструкции в CLAUDE.md, а автоматическая память Claude хранит образцы, которые она учится на исправлениях.^[2]

Звучит как конфигурация, но Anthropic делает важное различие. Эти инструкции входят в контекст модели; они не являются жёсткими правилами. Если "никогда не развёртывай в production" должно быть гарантировано, то PreToolUse hook или граница разрешения — подходящий уровень. Предложение в Markdown может направить поведение. Оно не может обеспечить гарантию безопасности.

Почему четырёхправильный файл стал вирусным

Репозиторий, теперь называемый multica-ai/andrej-karpathy-skills, говорит, что его директивы были выведены из публичных наблюдений Андрея Карпатова об ошибках моделей кодирования.^[3] Его популярность легко переусложнить. Каждое правило отображает знакомое разочарование на поведение, которое агент может выполнить.

Эти правила не учат TypeScript, дизайну БД или отладке. Они формируют, как модель подходит к неопределённости и масштабу. Это делает их переиспользуемыми в репозиториях.

Простота также социальна. Команда может прочитать четыре принципа за две минуты, поспорить с одним, отредактировать его и пересмотреть изменение в Git. Нет скрытой платформы с prompt для администрирования.

Четыре принципа, переведённые в поведение проекта

1. Думай перед кодированием

Исходная директива просит агента высказать предположения, представить несколько интерпретаций при необходимости, оспорить ненужную сложность и остановиться, если действительно смущен.^[3]

Специфичная для проекта формулировка делает её сильнее:

Перед изменением контракта API определи всех потребителей в репозитории и установи,
совместимо ли изменение с предыдущими версиями. Если поведение продукта неоднозначно,
остановись и спроси; не выбирай поведение молча.

Генерическое правило задаёт позицию. Конкретное дополнение говорит агенту, где неправильные предположения дорогостоящи.

2. Простота прежде всего

"Не усложняй" полезно по направлению, но трудно проверить. Добавь локальное определение "простоты" проекта:

Предпочитай существующую утилиту новой абстракции. Не вводи сервис,
factory или флаг конфигурации на одну call-site. Реализуй только запрошенное поведение;
перечисли опциональные follow-ups вместо их построения.

Это снижает предсказуемую тенденцию модели: решать гипотетическое семейство будущих проблем вместо текущей.

3. Хирургические изменения

Агенты видят возможности чистки рядом, потому что читают широко. Это не означает, что задача разрешает каждую чистку.

Каждая изменённая строка должна отслеживаться до запроса. Сохрани окружающее форматирование
и именование. Удали импорты, сделанные неиспользуемыми твоим редактированием, но
сообщи о несвязанном мёртвом коде вместо его удаления.

Меньшие дифы легче пересматривать, тестировать, откатывать и назначать. Они также снижают шанс, что агент сломает что-то, чего он не понял.

4. Целеустремлённое выполнение

Инструкция вроде "сделай работу" оставляет конечное состояние неопределённым. Переведи задачу в результат, который агент может проверить:

Для исправления ошибок воспроизведи сбой с тестом перед изменением production-кода.
Выполни самые узкие релевантные проверки во время итерации и требуемые проверки проекта перед завершением. Сообщи команды и результаты.

Здесь автономность становится полезной. Когда успех наблюдаем, агент может итерировать на сбоях вместо остановки после первого правдоподобного редактирования.

Что входит в CLAUDE.md

Anthropic рекомендует держать в CLAUDE.md факты, которые Claude должна хранить в каждой сессии, и перемещать многошаговые или узкие процедуры на более целевые механизмы.^[2] Полезный тест: "Повторил ли бы я это при подготовке почти для каждой задачи?"

Положи это в корневой файл

• описание проекта и архитектуры в один абзац;
• менеджер пакетов и канонические команды install, dev, test, type-check и build;
• владение директориями и границы сгенерированных файлов;
• правила, применяемые к языкам или пакетам;
• определение "готово";
• частые ошибки и их исправление;
• где найти глубокие инструкции.

Положи это куда-то ещё

Краткий шаблон CLAUDE.md

Скопируй как отправную точку, затем замени каждый элемент в скобках. Удали секции, которые не ограничивают твой проект.

# Инструкции проекта

## Проект

[Один абзац: что поставляет этот репозиторий, его основное время выполнения и самая
важная архитектурная граница.]

## Команды

- Установка: `[команда]`
- Разработка: `[команда]`
- Фокусированный тест: `[команда с файлом или паттерном]`
- Полный тест: `[команда]`
- Type-check: `[команда]`
- Сборка: `[команда]`

## Перед редактированием

- Прочитай ближайшую существующую реализацию и тесты перед предложением изменения.
- Высказывай предположения, которые влияют на публичное поведение, данные, безопасность или совместимость.
- Если запрос имеет несколько материально разных интерпретаций, спроси.

## Объём

- Реализуй только запрошенное поведение.
- Предпочитай существующие паттерны и утилиты новым абстракциям.
- Держи дифы хирургическими; не рефакторь смежный код, если не требуется.
- Удали только мёртвый код, созданный твоим изменением.

## Границы проекта

- `[путь]` сгенерирован; измени `[путь источника или команду]` вместо этого.
- `[пакет]` владеет `[ответственность]`; не дублируй в `[другой пакет]`.
- Никогда не выставляй `[категория секретных или приватных данных]` в логах или fixtures.

## Стиль

- [Два-пять правил, которые отличаются от defaults форматтера или легко упустить.]
- Соответствуй окружающему файлу, если нет явного правила.

## Проверка

- Для исправления ошибки добавь или обнови тест, который падает до исправления.
- Во время итерации выполни самую узкую релевантную проверку.
- Перед завершением выполни: `[требуемые команды]`.
- Сообщи изменённые файлы, выполненные команды, результаты и любой непроверенный риск.

## Глубокие инструкции

- Работа с API: `.claude/rules/api.md`
- Изменения БД: `[путь skill или документации]`
- Релизы: `[путь skill или документации]`

Шаблон намеренно простой. CLAUDE.md не должен читаться как мотивационный манифест. Он должен сокращать решения, которые агент иначе должен был бы угадывать.

Как Claude Code загружает несколько файлов инструкций

Claude Code идёт вверх по дереву директорий из текущей рабочей директории и загружает найденные файлы CLAUDE.md и CLAUDE.local.md. Инструкции ближе к директории запуска появляются позже в контексте. Вложенные файлы ниже рабочей директории загружаются, когда Claude читает файлы в этих поддиректориях.^[2]

Для monorepo это позволяет полезную иерархию:

repo/
├── CLAUDE.md                 # Факты проекта в масштабе организации
├── .claude/
│   └── rules/
│       ├── testing.md        # Общее правило без scope
│       └── api.md            # paths: packages/api/**
├── packages/
│   ├── web/
│   │   └── CLAUDE.md         # Web-специфичная архитектура и проверки
│   └── worker/
│       └── CLAUDE.md         # Ограничения runtime worker
└── CLAUDE.local.md           # Персональные локальные заметки разработчика

Файлы конкатенируются как контекст вместо поведения как strict override конфигурации. Противоречивые правила могут, следовательно, создать непоследовательное поведение. Пересматривай иерархию периодически и удаляй устаревшие инструкции.

Как улучшить файл из реальных ошибок

Не пытайся предсказать каждую возможную ошибку в день один. Начни маленько и используй повторяющееся трение как свой backlog.

1. Записывай ошибку. Что сделал агент и что ты ожидал?
2. Найди правильный уровень. Это универсальная инструкция, path-специфичное правило, процедура задачи или жёсткий контроль безопасности?
3. Напиши наблюдаемое правило. Замени "будь осторожен" действием и условием.
4. Протестируй на похожей задаче. Подтверди, что поведение улучшается без блокировки тривиальной работы.
5. Удали устаревшие правила. Контекст имеет цену; устаревшая инструкция может быть хуже, чем отсутствие инструкции.

Практический активатор Anthropic запоминается: добавь что-то, когда Claude совершает одну и ту же ошибку во второй раз, когда review находит знание, которое агент должен был иметь, или когда ты повторяешь одну и ту же коррекцию в сессиях.^[2]

Пять ошибок CLAUDE.md, которых следует избегать

Писать чаяния вместо инструкций

"Пиши отличный, надёжный код" не даёт новой информации. "Выполни pnpm test --filter api после изменений под packages/api" можно следовать и проверить.

Копировать гигантский генерический rulebook

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

Кодировать факты, которые агент может дёшево открыть

Редко нужно перечислять каждую директорию. Объясни границы, которые имена файлов не раскрывают, вроде какой пакет владеет авторизацией или какой источник генерирует проверенный клиент.

Обращаться с инструкциями как с контролями безопасности

Никогда не надейся на "не читай секреты" или "не разворачивай" как единственную защиту. Используй scoped credentials, разрешения, sandboxing и hooks для жёстких границ.

Никогда не пересматривай файл

Команды меняются, пакеты движутся и старые исключения становятся поведением по умолчанию. Назначь владельца и пересмотри CLAUDE.md как код.

Как узнать, работает ли это

Избегай судить файл по тому, выглядит ли одна демонстрация впечатляющей. Измеряй работу, которую команда уже пересматривает:

• среднее изменённых строк на завершённую задачу;
• неважные файлы затронуты;
• review комментарии, вызванные нарушениями соглашений репозитория;
• успех теста с первой попытки;
• задачи переоткрыты после заявленного завершения;
• повторные уточнения, которые должны стать постоянным контекстом.

Вирусный репозиторий предлагает те же самые результат-уровневые тесты: меньше ненужных изменений diff, меньше переписываний, вызванных переусложнением, и уточнение перед реализацией вместо после ошибок.^[3]

FAQ

Где должен идти CLAUDE.md?

Для инструкций проекта, совместных с командой, положи его в ./CLAUDE.md или ./.claude/CLAUDE.md и commit. Используй ~/.claude/CLAUDE.md для персональных инструкций в проектах и CLAUDE.local.md для персональных заметок в одном проекте.^[2]

CLAUDE.md работает с Cursor или другими агентами кодирования?

CLAUDE.md — это соглашение Claude Code. Вирусный репозиторий также поставляет правила Cursor и плагин, в то время как другие агенты могут использовать файлы вроде AGENTS.md или product-специфичные директории правил. Держи канонический источник и адаптируй его намеренно вместо предположения, что каждый инструмент загружает тот же файл.

Как долго должен быть CLAUDE.md?

Нет универсального счёта строк. Он должен содержать только информацию, ценную почти в каждой сессии. Если секция применяется к одной директории или одному workflow, перемести на path-scoped правило или skill.

Может ли CLAUDE.md остановить деструктивные команды?

Может велеть Claude не запускать их, но Anthropic явно описывает файл как контекст вместо конфигурации enforced. Используй разрешения или hooks для надёжной профилактики.^[2]

Как мне создать первый файл?

Выполни /init в Claude Code для генерации стартового CLAUDE.md, или создай файл Markdown вручную. Затем выполни /context для подтверждения, что он загружен, и /memory для инспекции или редактирования файлов памяти.^[4]

Файл простой, потому что проблема повторяющаяся

Агентам кодирования не нужна 500-строчная конституция перед тем, как они смогут исправить баг. Им нужно несколько фактов проекта, которые они не могут вывести, чёткая граница вокруг запрошенного изменения и проверка, которая отличает завершение от самоуверенности.

Вот почему четыре простых правила прошли так далеко. Они решают ошибки, которые разработчики видят каждый день, живут в формате, который вся команда может редактировать, и загружаются перед тем, как агент начинает принимать решения. Начни там. Добавь знание проекта только когда оно предотвращает реальный сбой и enforсируй критические границы вне prompt.

Если ты новичок в самом инструменте, начни с более широкого гида по использованию Claude Code. Используй эту статью, когда установка завершена и следующий вопрос: что твой агент должен знать каждый раз, когда входит в репозиторий.

References

1. GitHub REST API. multica-ai/andrej-karpathy-skills repository metadata. Retrieved August 2, 2026. api.github.com
2. Anthropic. How Claude remembers your project. Claude Code Docs. Retrieved August 2026. code.claude.com
3. multica-ai. Karpathy-Inspired Claude Code Guidelines. GitHub. Retrieved August 2026. github.com
4. Anthropic. Claude Code commands. Retrieved August 2026. code.claude.com
5. Sumit Pandey. A Single CLAUDE.md File Went Viral. The Reason Is Embarrassingly Simple. Towards Deep Learning, May 2026. towardsdeeplearning.com

Further reading

• reAPI. How to use Claude Code. reapi.ai/blog/how-to-use-claude-code
• reAPI. How to get a Claude API key. reapi.ai/blog/how-to-get-claude-api-key
• reAPI. Claude model catalog. reapi.ai/models