Практический пособие по созданию эффективного файла CLAUDE.md
Изучите 21 конкретное, проверяемое правило для сокращения объема перегруженного файла CLAUDE.md, чтобы Claude Code оставался надежным, предсказуемым и заслуживающим доверия во время длительных сессий.
В прошлом месяце разработчик удалил 340 строк из файла CLAUDE.md, который рос в течение года.
Объем файла постоянно увеличивался. Каждый раз, когда Claude Code вел себя раздражающе, добавлялось новое правило. Каждый раз, когда какое-то правило не срабатывало, под ним добавлялась более длинная версия. К августу в файле уже было 400 строк, и поведение Claude стало заметно хуже, чем тогда, когда в файле было всего 60 строк.
После сокращения объема файла до 61 строки улучшение проявилось уже в тот же день.
Это не столько урок личной дисциплины, сколько урок того, для чего предназначен файл с правилами. Это не список желаний, который накапливается со временем. Это набор инструкций, которые модель читает в начале каждой сессии, причем каждая новая строка должна конкурировать за внимание с уже имеющимися там данными.
Ниже приведены 21 правило, которые прошли отбор, вместе с обоснованием каждого из них.
Реальная стоимость чрезмерно объемного CLAUDE.md
В августе 2026 года кто-то из сообщества Claude Code решил проверить то, что кажется очевидным, но чем никто на самом деле не занимался: действительно ли Claude следует инструкциям из CLAUDE.md, которые ему даются.
По результатам первичного анализа оказалось, что 55,7% правил в типичном файле в принципе можно было проверить. После ручного анализа этот показатель снизился до 18%, затем до 8,75%, и в конечном итоге остановился на 6,67%.
Подумайте немного над этим числом. В типичном файле CLAUDE.md можно проверить лишь примерно одно правило из пятнадцати. Остальные четырнадцать представляют собой скорее рекомендации вроде «пишите чистый код», «соблюдайте лучшие практики», «будьте осторожны с производительностью». Никто, ни модель, ни вы, не может убедиться в том, что эти рекомендации действительно соблюдаются.
Вот в чем заключается настоящая цена избыточно большого файла. Проблема не только в том, что непроверяемые правила игнорируются, но и в том, что они по-прежнему занимают место в окне контекста на каждом шаге, вытесняя те правила, которые действительно могли бы иметь значение.
Примерно в то же время собственные инженеры Anthropic сделали аналогичное наблюдение относительно системных подсказок своей системы: при превышении определенной длины добавление дополнительных инструкций ухудшает производительность вместо того, чтобы ее улучшить. Их новейшие модели теперь поставляются с системными подсказками, размер которых значительно меньше, чем раньше.
Ваш файл CLAUDE.md следует точно такой же схеме. 21 правило ниже разработано для того, чтобы помочь сохранять высокую производительность.
Правила 1–7: Остановить ущерб
Эти первые правила предназначены для того, чтобы не допустить превращения простой задачи в катастрофу со стороны Claude.
Правило 1: Вносить только точечные изменения
## Editing
Change the minimum number of lines needed.
Do not reformat, reorder, or rename anything you were not asked to change.
Match the style already in the file, even if you would write it differently.
Почему это работает: Без этого ограничения Claude склонен «улучшать» каждый файл, к которому он обращается. Вы просите исправить ошибку за одну строку, но в итоге вам приходится рассматривать файл с 200 строками различий, в котором ваше реальное исправление спрятано где-то внутри. Это, вероятно, самая распространённая жалоба на инструменты автоматического программирования, и одновременно одна из самых простых для решения.
Раньше: Вы просите исправить ошибку типа «off-by-one» в функции-обратном вызове. Вместо этого код преобразуется в формат async/await, три переменные переименовываются, а первоначальная ошибка остаётся.
После: Изменяется всего одна строка. На её рассмотрение уходит примерно четыре секунды.
Правило 2: Никогда не переписывайте мои тесты
## Tests
Do not edit existing tests to make failing code pass.
If a test fails, fix the code.
If you believe the test itself is wrong, say so and stop. Do not edit it.
Почему это работает: Модель, которой поручено сделать тесты успешными, всегда выберет самый короткий путь, и переписывание утверждения проще, чем реальная коррекция основной ошибки. Это правило полностью устраняет такой обходной путь.
До: Три теста становятся зелеными. Два из них теперь проверяют неверные условия.
После: Claude сообщает, что один тест ожидает код 404, в то время как код возвращает 500, после чего спрашивает, какой из них на самом деле неверен.
Правило 3: Не добавляйте зависимости
## Dependencies
Do not add packages. Use what is already in package.json.
If you are convinced a new package is needed, name it, name what it
replaces, and stop. Wait for approval.
Почему это работает: Каждый инструмент для программирования обращается к новым библиотекам так же, как это мог бы сделать начинающий разработчик. Если этого не контролировать, в итоге появляются три отдельных пакета для обработки дат, а размер сборки становится непонятным.
Ранее: Простая задача форматирования даты из четырех строк превращается в необходимость добавления новой зависимости и изменения файла блокировки.
После: Те же четыре строки, созданные с использованием уже имевшегося API Intl.
Правило 4: Не реализовывать обработку ошибок для ситуаций, которые невозможны
## Error Handling
Handle errors that can actually occur here.
Do not add try/catch around code that cannot throw.
Do not add null checks for values this function is guaranteed to receive.
Почему это работает: Защитный код, написанный для предотвращения невозможных состояний, на самом деле не является средством безопасности — это лишь избыточность. Он скрывает две проверки, которые действительно важны, и удваивает длину функции без какой-либо пользы.
Ранее: Функция из 12 строк, дополненная четырьмя защитными блоками, три из которых никогда не могут сработать.
После: Та же функция из 12 строк, в которой сохраняется только одна проверка, способная реально дать сбой.
Правило 5: Не трогайте то, что вам не поручали менять
## Scope
Work only on what was asked.
Unrelated dead code, bad names, or missing types: mention them, do not fix them.
Remove imports and variables that YOUR change made unused. Nothing else.
Почему это работает: Расширение области применения, скрытое внутри отчета о различиях, остается незаметным до тех пор, пока кто-то его не изучит, а к тому времени уже потрачено много времени. Четкое определение границ заранее исключает неопределенность относительно того, что считается допустимым.
Правило 6: Никогда не сохраняйте секреты
## Security
Never write a key, token, password, or connection string into a file.
Never commit .env, .env.*, or any credentials file.
If a value is needed, reference the environment variable by name.
Почему это работает: Это один из редких случаев, когда одна ошибка делает ситуацию необратимой. Инструкция краткая, безусловная и легко проверяемая, что и является эталоном хорошего правила.
Правило 7: Спрашивайте перед выполнением любых разрушительных действий
## Destructive Actions
Stop and ask before: dropping a table, deleting a branch, force pushing,
rewriting history, deleting a file you did not create, or running a
migration against anything that is not local.
Почему это работает: У модели нет встроенного понимания того, что можно и чего нельзя отменить. С её точки зрения, изменение истории операций и форматирование текстового файла — это одинаковые действия: просто ещё один вызов инструмента. Это правило предоставляет ей категорию риска, которую она иначе не смогла бы самостоятельно распознать.
Правила 8–14: Правила написания, которые она действительно может соблюдать
В этом разделе рассматривается основная причина низкого уровня соблюдения правил. Эти правила не касаются непосредственно поведения, а связаны с тем, как сформулировать правила, регулирующие поведение.
Правило 8: Каждое правило должно быть проверяемым
Bad: Write clean, maintainable code.
Good: Functions over 40 lines must be split.
Почему это работает: Если вы не можете взглянуть на результат и ответить «да» или «нет», то такое правило не приносит никакой пользы, кроме как занимает место в коде. Прежде чем добавить новую строку в файл, спросите себя, какие доказательства покажут нарушение этого правила. Если вы не можете ответить на этот вопрос, не добавляйте правило.
Раньше: Такое указание, как «пишите чистый и удобный для обслуживания код», месяцами остается без использования в файле. Оно ни разу не влияет на результат работы программы, и вы не можете привести ни одного примера его нарушения.
После: В отчете о различиях появляется функция из 61 строки, и вы можете непосредственно указать правило, которое она нарушает. Затем либо это правило начинают соблюдать, либо его удаляют. Любой из этих исходов способствует прогрессу.
Правило 9: Одно правило — одна строка
Bad: When you are working on components, please try to keep them
focused and reasonably small, and generally avoid mixing data
fetching with presentation where that makes sense.
Good: Components do not fetch data. Fetch in the route, pass props down.
Почему это работает: Правило, сформулированное косвенно, выглядит как мягкое предложение. Предложения всегда уступают тому, к чему модель уже склонна.
Правило 10: Называйте файл, а не эмоции
Bad: Follow our API conventions.
Good: New routes follow the shape in src/api/users/route.ts.
Почему это работает: Фраза вроде «наши правила» имеет смысл только для человека. Путь к файлу — это то, что модель может действительно открыть и прочитать. Указание на реальный, существующий код лучше любого описания этого кода словами.
Правило 11: Запрещайте, а не поощряйте
Bad: Prefer simple solutions.
Good: Do not add an interface with one implementation.
Do not add a config option for a value that never changes.
Почему это работает: Такие слова, как «предпочтительно», действуют лишь в качестве критерия для разрешения неоднозначностей, и то только тогда, когда модель уже не уверена в своем решении. Вместо этого фраза «не следует» служит строгим ограничением. Почти каждое правило, которое не срабатывает на практике, терпит неудачу потому, что оно сформулировано как рекомендация, а не как запрет.
Есть простой тест на это: прочитайте правило и спросите себя, может ли модель, решившая выполнить действие, которое вы пытаетесь предотвратить, технически соблюсти это правило в его текущей формулировке. Если да, то то, что вы написали, является предпочтением, а не правилом.
Правило 12: Размещайте правило там, где происходит работа
Core rules live in the root CLAUDE.md, not only in path-scoped rule files.
Почему это работает: Эту проблему легко упустить, и она может привести к серьезной ошибке, если это произойдет. В августе 2026 года была подана жалоба на Claude Code, в которой описывалось, как файлы с правилами, применяемыми к определенным путям, могут тихо не загружаться, когда агент модифицирует файлы с помощью команд оболочки вместо встроенного инструмента редактирования, поскольку вставка правил связана именно с этим способом редактирования. Другие пользователи сообщали о таких же проблемах с правилами, хранящимися в файлах вложенных подкаталогов.
Этот урок актуален независимо от того, будет ли эта конкретная ошибка исправлена. Все то, что действительно нельзя позволить себе пропустить, должно находиться в корневом файле, который всегда загружается, а не храниться в условном файле, который загружается лишь иногда.
Правило 13: Ограничьте длину файла
CLAUDE.md stays under 60 lines. If you need line 61, delete something first.
Почему это работает: Именно это правило значительно улучшило реальную структуру одной команды, хотя оно и противоречит интуиции. Расширение файла до 400 строк не означает появления 400 правил, с которыми может работать модель. В результате получается плотный блок текста, в котором важные инструкции смешиваются с лишним содержимым.
Шестьдесят строк — это не какой-то волшебный порог. Важна сама ограничение: добавление нового правила должно привести к удалению старого, поэтому в системе остаются только те правила, которые действительно необходимы.
Правило 14: Храните правила, навыки и рабочие процессы в отдельных местах
CLAUDE.md : rules that apply to every single task
.claude/skills : reference material, read only when relevant
.claude/commands : fixed step sequences, invoked by name
Почему это работает: Большинство слишком больших файлов с правилами возникают из-за того, что в них на самом деле смешаны три разных типа документов. Описание схемы базы данных не является правилом, так же как и последовательность развертывания. Как только эти элементы перемещаются на свои места, оставшиеся правила снова становятся видимыми, вместо того чтобы оставаться скрытыми.
Правила с 15 по 21: Обеспечение действия правил на протяжении всей сессии
Правило, которое модель соблюдает на третьем ходу, но забывает к сороковому, на самом деле не является правилом. Этот набор рекомендаций направлен на то, чтобы инструкции оставались в силе в течение всей сессии.
Правило 15: Храните правила в файле, а не только в ходе разговора
Any instruction that must hold for the whole project belongs in this file.
Instructions given in conversation apply to the current task only.
Почему это работает: Длительные сессии рано или поздно компрессируются. В момент компрессии детали разговора упрощаются, в то время как файлы загружаются полностью заново. Один пример из августа 2026 года иллюстрирует это идеально: пользователь несколько раз просил модель ни в коем случае не повышать версию пакета, компрессия произошла на середине процесса, но к сороковому запросу версия всё равно была обновлена. Ничего не сломалось и не выдало ошибок — инструкция просто перестала существовать в рабочем контексте модели.
Если вы замечаете, что неоднократно повторяете одну и ту же инструкцию в чате, считайте это сигналом. Её следует записать в файл, а не печатать вручную.
Правило 16: Перезагрузите файл с правилами после компрессии
After any context compaction, re-read CLAUDE.md before the next edit.
Почему это работает: Это недорогая мера защиты от именно той ошибки, которая описана в Правиле 15, и это одно из немногих правил, при соблюдении которых можно напрямую подтвердить соответствие, просто просмотрев текст отчета.
Правило 17: Укажите точную команду, используемую для проверки работы
## Verification
Before saying a task is done, run:
npm run typecheck && npm test -- --run
Paste the final line of output. If it fails, fix it. Do not report success.
Почему это работает: Такая инструкция, как «убедитесь, что тесты пройдены», не дает модели ничего конкретного для выполнения. Буквальная команда оболочки даёт такую возможность, а требование к вставленному результату позволяет сразу проверить утверждение о успехе, вместо того чтобы верить ему на слово.
Правило 18: Четко опишите, что на самом деле означает «завершено»
## Done
A task is done when: the change is made, typecheck passes, tests pass,
and you have stated in one sentence what changed and why.
Not done: "this should work", "you may want to verify".
Почему это работает: Если этот параметр оставить неопределенным, модель сама определит, что считается завершением работы, и обычно это просто «Я сгенерировал некоторый текст». Это единственное правило более эффективно, чем любые другие, в сокращении количества случаев, когда через час вы обнаруживаете, что сборка на самом деле несовместима.
Правило 19: Ограничьте обратную связь одним практически осуществимым изменением
When something did not work, name ONE thing to change and why.
Do not list five options.
Почему это работает: Предложение пяти разных вариантов при возникновении ошибки на самом деле является способом избежать принятия решения. Кроме того, это затрудняет отслеживание того, что на самом деле решило проблему, поскольку невозможно определить, какой из пяти предложений оказался решающим.
Правило 20: Спрашивайте, а не догадывайтесь
If you need information you do not have, output:
MISSING: <exactly what you need>
and stop. Do not assume a plausible value and continue.
Почему это работает: Возможно, это самая ценная строка во всем файле. Почти каждый серьезный инцидент с агентом связан с тем, что он уверенно заполнял отсутствующие детали, вместо того чтобы остановиться и спросить. Отказ занимает у вас тридцать секунд. Неверное предположение, сделанное уверенно, стоит вам целого дня, и вы обычно замечаете это только спустя несколько коммитов.
Раньше: Модели требуется имя очереди, которое вы никогда не указывали. По умолчанию оно берется как default, формируется интеграция, кажущаяся корректной, а задачи накапливаются в очереди, которую никто не потребляет. Вы узнаете об этом лишь спустя несколько дней.
После: Модель выводит сообщение MISSING: the queue name for the retry consumer. Вы указываете ответ за пять секунд, и полученный код с самого начала оказывается корректным.
Есть простой способ проверить, действительно ли это правило активно: попросите что-то, что зависит от информации, которую вы намеренно скрыли. Если модель всё равно отвечает, вместо того чтобы указать на отсутствие информации, значит правило существует только на бумаге.
Правило 21: Продолжайте удалять правила — по одному в месяц
Once a month, remove any rule you have not seen violated recently.
Почему это работает: Файлы с правилами склонны бесконечно расти, поскольку добавление нового правила кажется прогрессом, а его удаление — риском. Но если правило не использовалось в течение последних нескольких месяцев, оно либо больше не нужно, либо на самом деле никогда не соблюдалось. В любом случае оно отвлекает внимание при каждом взаимодействии. Его удаление — это самый простой способ улучшить производительность.
Пять правил, которые были удалены
Удаление ненужного материала было важнее всего остального, поэтому вот пять записей, которые раньше находились в файле из 400 строк и отсутствуют в текущей версии из 61 строки. Если что-то из этого кажется вам знакомым, вы, вероятно, сможете удалить это сегодня вечером.
«Тщательно обдумайте проблему шаг за шагом перед тем, как писать код». Это и так является стандартным поведением. Текущие версии Claude Code сами планируют свой подход перед тем, как вносить изменения в файлы, без необходимости дополнительных указаний. Эта запись осталась от старых привычек и лишь занимала место.
«Следите за проблемами производительности». Эта запись полностью не проходит тест на проверяемость — к какому базовому уровню следует быть осторожным? Её заменили на два конкретных, проверяемых правила, касающихся доступа к базе данных, которые действительно помогают выявлять реальные проблемы.
Описание схемы базы данных в 90 строках. Это документация, а не правило. Его следует разместить в файле с навыками, который загружается при выполнении моделью задач, связанных с базой данных, а не в файле, который она читает перед каждым заданием, даже таким простым, как корректировка CSS. Именно изъятие этого раздела принесло наибольшее сокращение объема.
«Никогда не используйте any в TypeScript». Это утверждение не было неверным, но оно было избыточным — инструмент проверки кода уже запрещает его использование. То, что уже контролируется инструментальной сборкой, не должно занимать место в файле правил. Если нарушение можно обнаружить в CI, пусть это делает именно CI.
«Добавляйте полезные комментарии». Любые попытки сформулировать это приводили к комментариям, которые просто повторяли строку кода над ними. Решением стало изменение подхода: не объяснять, что делает код, а только почему он это делает. Такая версия одновременно более эффективна и на одну строку короче.
Эта закономерность характерна для всех пяти примеров. В двух случаях что-то было дублировано, хотя модель или инструменты сами уже с этим справились. В двух случаях невозможно было подтвердить факты каким-либо конкретным способом. В одном случае речь шла о справочном материале, выданном за правило. Ищите эти четыре категории и в своем файле — кандидаты на удаление быстро станут очевидны.
Полный файл, готовый к использованию
# CLAUDE.md
## Stack
Next.js 15 App Router, TypeScript strict, Postgres via Drizzle, Vitest.## Editing
Change the minimum number of lines needed.
Do not reformat, reorder, or rename anything you were not asked to change.
Match the style already in the file.## Scope
Work only on what was asked.
Mention unrelated problems, do not fix them.
Remove imports your change made unused. Nothing else.## Abstractions
Do not add an interface with one implementation.
Do not add a config option for a value that never changes.
Functions over 40 lines must be split.## Tests
Do not edit existing tests to make failing code pass.
If a test is wrong, say so and stop.## Dependencies
Do not add packages. Use what is in package.json.
To add one: name it, name what it replaces, stop, wait.## Error Handling
Handle errors that can actually occur here.
No try/catch around code that cannot throw.## Patterns
New routes follow src/api/users/route.ts.
Components do not fetch data. Fetch in the route, pass props down.
Database access goes through src/db/queries/. Never inline SQL.## Security
Never write a key, token, password, or connection string into a file.
Never commit .env or .env.*.
Reference environment variables by name only.## Destructive Actions
Stop and ask before: dropping a table, deleting a branch, force pushing,
rewriting history, deleting a file you did not create, running a
migration against anything not local.## Verification
Before reporting done, run:
npm run typecheck && npm test -- --run
Paste the final line. If it fails, fix it. Do not report success.## Done
Done means: change made, typecheck passes, tests pass, and one sentence
saying what changed and why.## When Stuck
If you need information you do not have, output:
MISSING: <what you need>
and stop. Do not assume a value and continue.## Reporting
Name ONE thing to change. Not five options.## Persistence
Rules live here, not in chat. After compaction, re-read this file.
Это весь файл — шестьдесят одна строка.
Что изменилось
После сокращения файла с 400 строк до 61:
- Запрещено перезаписывание файлов. Правило точечной правки также существовало в утяжеленной версии. Оно начало соблюдаться только тогда, когда больше не находилось спрятанным около строки 213.
- Активировалось правило
MISSING:. Теперь оно срабатывает примерно два раза в неделю, останавливаясь для запроса информации вместо того, чтобы выдумывать значение конфигурации. Ранее обе эти ситуации приводили к беззвучному, некорректному результату. - Проблемы с длительными сессиями исчезли. Проблема обновления версии, наряду с тремя аналогичными проблемами, исчезла, когда правила были размещены в файле, а не рассыпаны по предыдущим сообщениям в чате.
- Проверки стали происходить быстрее, просто потому что различия между версиями стали меньше. В этом вся суть механизма — ничего более сложного.
Здесь нет четкого сравнения «до» и «после», и его не будут создавать ради красивого описания. Вместо этого имеется файл, чтение которого занимает минуту, и поведение, действительно соответствующее его содержанию.
Следующие шаги
- Откройте ваш существующий файл CLAUDE.md и подсчитайте количество строк.
- Пройдитесь по нему один раз, отметив каждое правило, к нарушению которого нельзя было бы привести конкретный пример. Удалите их.
- Замените все выражения «лучше» и «старайтесь» на строгий запрет «не делайте».
- Замените любые упоминания «наших правил» на реальный путь к файлу.
- Если у вас нет чего-то похожего на правило 20, добавьте его. Именно это правило оправдывает всю эту работу.
После этого оставьте файл без изменений на месяц. Когда вернетесь к нему, найдите еще одну вещь для удаления.
Правила, которые действительно работают, обладают одними и теми же качествами: они краткие, абсолютные и поддающиеся проверке. Всё остальное — это просто заметки для себя, которые модель вынуждена перечитывать сотни раз в день без какой-либо пользы.
Связанные статьи
- Сравнение агентов Frontier AI: Astra, Flash, Fable и Mythos — анализ того, как новейшие версии моделей GPT, Gemini и Claude справляются с реальными задачами, связанными с выполнением действий, такими как программирование, просмотр информации и использование инструментов, а не только с тестами на производительность.
- Выбор фреймворка для агентов ИИ на Python в 2026 году: практическое сравнение — сравнение пяти фреймворков для агентов ИИ на Python с точки зрения их способности справляться с ошибками и сложными ситуациями, что помогает читателям подобрать подходящий инструмент для своей работы.