Настройка Claude Code с восемью уровнями: CLAUDE.md, память, хуки и ограничения

Настройки определяют степень доверия к ответу

Любой может ввести запрос в Claude Code, но именно настройки вокруг него определяют, заслуживает ли результат доверия. Далее приводится пошаговый обзор реалистичной конфигурации для серьезной инженерной работы вместе с обоснованием каждого слоя. Это не список функций и не маркетинговая версия. Восемь слоев вместе создают что-то более похожее на хорошо настроенный инженерный инструмент, чем просто окно чата, случайно пишущее код.

Слой 1: CLAUDE.md в двух уровнях доступа

Claude Code читает файлы CLAUDE.md в нескольких областях, и разделение между ними имеет большее значение, чем предполагают большинство людей. Личный файл, находящийся по пути ~/.claude/CLAUDE.md, применяется во всех проектах, независимо от открытого репозитория. Каждый проект также имеет свой собственный файл CLAUDE.md, который сохраняется в системе контроля версий, так что вся команда читает одни и те же инструкции через систему контроля версий.

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

Причина для записи чего-либо всегда конкретна. Представьте себе паттерн ошибки, который встречается дважды в одной и той же части проекта. Решение кажется правильным и проходит поверхностную проверку, но при этом снова приводит к той же проблеме, поскольку основное ограничение нигде не было зафиксировано так, чтобы его мог увидеть сотрудник. В первый раз ограничение объясняется в ходе разговора, и все продолжают работу. Во второй раз та же ошибка требует того же объяснения. В этот момент появляется сигнал к действию: правило должно быть записано в CLAUDE.md не потому, что оно может пригодиться в будущем, а потому, что из-за него одна и та же дискуссия повторялась дважды. Как только правило становится конкретным и проверяемым, а не расплывчатым предупреждением, проблема перестаёт возникать.

Один практический момент: содержимое CLAUDE.md передаётся в виде сообщения от пользователя и не встроено в системный промпт, поэтому конкретность важнее длины. Файл с менее чем 200 строками чётких правил эффективнее длинного файла с неопределёнными правилами.

Уровень 2: автоматическая память

CLAUDE.md — это то, что разработчик сообщает агенту, а память — это то, что агент формирует самостоятельно. Они выполняют разные функции и не должны путаться. У Claude Code есть вторая система — автоматическая память, которая формируется для каждого проекта и хранится вне репозитория; именно агент записывает в неё данные. В ней хранятся четыре вида заметок: роль разработчика и его предпочтения в работе, уже данная коррекция и обратная связь, текущее состояние проекта, которое невозможно определить из кода, и внешние ссылки на информацию, находящуюся вне кодовой базы. Лёгкий файл MEMORY.md индексирует всё это.

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

• Единоразовые указания, такие как «не трогайте этот файл, не спросив сначала», переносятся в следующую сессию и не требуют повторения при каждом начале обсуждения.
• Состояние проекта, невидимое в коде, запоминается: процесс миграции, решение, намеренно отложенное, или архитектура, которая выглядит некорректно из-за ограничения, не отражаемого в отчетах о изменениях.
• Сохраняются указатели на места, где находятся ответы, например, какой панель управления, какой внешний документ или какая система содержат информацию, которую кодовая база не может сообщить.

Ничто из этого не должно находиться в CLAUDE.md, поскольку ни одно из этих положений не является обязательным правилом. Это контекст, который исчезнет сразу после завершения сессии.

Уровень 3: хуки как умышленные препятствия

Умышленно созданные препятствия совершенно не похожи на те, с которыми приходится сталкиваться автоматически. Хуки выполняются детерминированно, как настоящие команды оболочки в определённые моменты жизненного цикла, что является более надёжной гарантией, чем надежда на то, что модель обычно всё запомнит. Хук PreToolUse активируется перед любым вызовом инструмента и может полностью его остановить. Хук Stop активируется, когда Claude завершает свой ответ, и может заставить его продолжиться, если какое-то условие ещё не выполнено.

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

Второй хук обеспечивает дисциплину вывода, делая ответы краткими, удаляя излишние формулировки и неопределенности, которые появляются в длительных сессиях. Речь идет скорее не о безопасности, а о том, чтобы не тратить время на лишний текст. Третий хук отслеживает состояние контекста, способствуя его сжатию в естественных моментах, а не произвольно. Хук PreCompact или SessionStart, связанный с событиями сжатия, может выдать краткое резюме, когда разговор действительно достигает точки завершения, чтобы его не прервали на полуслове.

Оправдывает ли такая сложность себя? Что касается механизма контроля редактирования файлов, то безусловно, ведь он предотвращает настоящие ошибки до того, как они превратятся в серьезные проблемы. Хуки, отвечающие за краткость и контекст, больше служат настройкой для удобства, чем защитой, но они полезны при правильной настройке.

Уровень 4: граф знаний кода превосходит grep

Grep показывает, где встречается строка, но не то, что её вызывает, куда она обращается или что ломается при её изменении. Классический способ исследования представляет собой цикл: искать термин, открывать файл, искать содержимое импортируемых им файлов, открывать их тоже, и продолжать до тех пор, пока не сформируется полная картина. Этот метод работает, но медленно, и требует множества вызовов инструментов для воссоздания умственной модели, основанной на структурных фактах, которые не должны переоткрываться с нуля силой brute force при каждой сессии.

Заранее индексированная графа знаний меняет экономику работы системы. Один запрос возвращает соответствующий источник вместе с реальными путями вызовов: кто его вызывает, что он вызывает и насколько длинна цепочка зависимостей. Эта информация получается за один проход вместо множества поисков, поэтому сокращается количество обратных запросов, и с самого начала формируется более полная картина, поскольку детали путей вызовов, которые grep никогда бы не смог выдать, поставляются вместе с результатом. В официальной документации Claude Code излагается нечто подобное относительно плагинов для анализа кода, где отмечается, что крупные типизированные кодовые базы получают значительную выгоду от запросов, учитывающих структуру, по сравнению с поиском по тексту, при котором повторяющиеся циклы поиска и чтения быстро становятся дорогостоящими.

Уровень 5: проверка на реальном устройстве

Важно понимать, работает ли изменение на устройстве или оно лишь скомпилировано — это два разных варианта. Для Flutter именно этот слой используется чаще всего. Пересоздавать проект с нуля для проверки небольших изменений интерфейса — это расточительство, когда есть возможность подключиться к приложению, работающему на реальном оборудовании; такое подключение позволяет заполнить пробелы, до которых не может дотянуться генерация кода. Оно поддерживает снимки экрана, прокрутку по элементам интерфейса и просмотр живой структуры интерфейса. Claude Code теперь корректно поддерживает это, предоставляя доступ к симулятору iOS и функции работы на компьютере, которые позволяют проверять нативную версию приложения, воспроизводить ошибки макета или запускать сценарии симулятора для сравнения с реальным отображением.

Подключение к виртуальной машине Dart для горячей замены кода и горячего перезапуска преобразует процесс из этапов «угадай, пересобери, подожди, проверь» в «угадай, загрузи заново, проверь». Это делает работу быстрее, к тому же избавляет от частой ошибки — считать успешную компиляцию доказательством того, что исправление сработало. Успешная компиляция и правильная работа программы на аппаратном обеспечении — это разные вещи, и привычка пересобирать код не позволяет их различить. Запуск программы на устройстве дает однозначный ответ на этот вопрос.

Уровень 6: загружать инструменты только по мере необходимости

Каждый инструмент, находящийся в контексте, независимо от того, используется ли он или нет, влияет на каждый этап работы, а не только на те этапы, где он применяется. Поэтому не все инструменты загружаются по умолчанию, и это осознанный дизайнерский выбор. Специализированные инструменты, такие как автоматизация браузера, реже встречающиеся серверы MCP и всё, что используется эпизодически, загружаются по требованию и не занимают ресурсы контекста на протяжении всей сессии.

Этот эффект нарастает в течение длительной сессии, поскольку каждое определение инструмента стоит токенов на каждом ходу, независимо от того, используется ли этот инструмент на данном ходу. Функция поиска инструментов MCP в Claude Code предназначена для решения этой проблемы. Серверы могут зарегистрироваться для поиска по запросу вместо загрузки всех определений сразу при начале сессии, что позволяет сохранять эффективность сессий продолжительностью в несколько часов и избегать нагрузки от ненужного контекста, который так и не используется, но продолжает потреблять ресурсы.

Слой 7: используйте те готовые рабочие процессы, которые вам действительно нужны

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

Три из них используются регулярно. Сначала проводится общий анализ кода перед любым значимым слиянием. Специалист, сосредоточенный на безопасности, проверяет всё, что связано с аутентификацией или обработкой данных. Отдельный агент для планирования занимается задачами достаточно большими, чтобы сразу перейти к реализации привело к игнорированию настоящего архитектурного обдумывания. Эти три инструмента покрывают почти все случаи прямого использования.

Большинство специализированных инструментов для фреймворков, не используемых в настоящее время, остаются без внимания, как и более сложные схемы агентов, разработанные для крупных параллельных исследовательских проектов. Это не плохие инструменты. Ежедневная работа просто не требует такого уровня исследований, а использование более мощных инструментов, чем необходимо, — это пустая трата ресурсов. Ценность заключается в знании трех-четырех инструментов, которые можно использовать надежно, без необходимости применять остальные только потому, что они существуют.

Слой 8: подтверждение через обратимость

Скорость считается преимуществом только тогда, когда результат остается надежным; как только доверие уменьшается, именно скорость становится причиной ущерба. Даже при активации всех уровней контроля некоторые действия всегда требуют явного подтверждения: разрушительные операции в Git, отправка изменений и всё то, что действительно необратимо. Никакой уровень автоматизации не может снять этот запрет, потому что ошибка в таких случаях означает не просто необходимость переработки работы, а устранение ущерба, который может оказаться неисправимым.

Решающим фактором является степень обратимости конкретного действия, а не ощущаемый уровень риска. Масштабная переработка десятков файлов требует значительных усилий, но остается полностью обратимой благодаря системе контроля версий, поэтому её можно выполнять при более слабом контроле. Однако команда git push --force практически не требует усилий, но может привести к необратимым последствиям, поэтому её использование строго запрещено, как бы рутинной она ни казалась. Усилия и риск находятся на разных осях, и именно смешивание этих факторов приводит к тому, что чрезмерная автономия оказывается в руках неподходящих действий.

Выбор между немедленными действиями и предварительным запросом разрешения не сводится к одному параметру. Это решение, принимаемое для каждого типа действия заранее, и оно не пересматривается в момент, когда усталость заставляет подтверждающее сообщение казаться раздражающим препятствием.

Что дают эти уровни

Ни один из восьми слоев не выделяется сам по себе. CLAUDE.md — это файл простого текста, а хук — это команда оболочки, которая выполняется в подходящий момент. Вместе они превращают Claude Code из быстрого вводчика текста, не обладающего постоянным контекстом и никаким пониманием возможности возврата к предыдущему состоянию, в инструмент с памятью, ограничениями, структурным пониманием кодовой базы и возможностью реальной проверки на устройстве.

Сама настройка не является самой интересной частью; интересным является обоснование каждого слоя. Те, кто использует Claude Code без какой-либо настройки, не должны пытаться добавить все восемь слоев сразу. Начните с реального файла CLAUDE.md, созданного на основе ошибок, которые уже возникали дважды, а затем постепенно расширяйте его функционал.