Это перевод статьи разработчика нескольких мега-популярных инструментов -https://github.com/tw93. Она была опубликовала в твиттере на китайском языке, потом криво переведена на английский, я пытался было взять какие-то части для себя и для канала, но тут в каждом абзаце просто кладезь ценного, так что решил перевести статью полностью на русский и опубликовать.
Сегодняшняя статья основана на полугодовом опыте глубокого использования Claude Code и кучи набитых шишек. Надеюсь, это будет полезно.
Поначалу я использовал его как обычный чат-бот, но довольно быстро понял, что что-то идёт не так: контекст становился всё более хаотичным, инструментов становилось всё больше, но эффективность только падала, правила становились всё длиннее, но соблюдались всё реже. После некоторого времени ковыряния и изучения самого Claude Code я осознал – это не проблема промптов, а особенность архитектуры самой системы.
В этой статье я хочу обсудить несколько вещей: как Claude Code работает изнутри, почему контекст засоряется и как с этим бороться, как правильно проектировать Skills и Hooks, как правильно использовать Subagents, как архитектура Prompt Caching влияет на всё, и как написать действительно полезный CLAUDE.md.
Мне кажется, самый наглядный способ понять Claude Code – разложить его на шесть слоёв:
Если усиливать только один слой, система разбалансируется. CLAUDE.md слишком длинный – контекст загрязняет сам себя; инструментов слишком много – выбор становится непонятным; subagents запущены повсюду – состояние начинает дрейфовать; проверка пропущена – при ошибке вообще непонятно, где сломалось.
1. Как это работает изнутри
Ядро Claude Code – это не «ответы», а повторяющийся агентный цикл:
Сбор контекста → Действие → Проверка результата → [Готово или обратно к сбору] ↑ ↓ CLAUDE.md Hooks / Разрешения / Песочница Skills Tools / MCP Memory
Спустя время я понял, что застревание почти никогда не связано с тем, что модель недостаточно умна. Чаще всего проблема в том, что ей дали неправильный контекст, или она что-то написала, но нет возможности проверить правильность и откатить.
Пять ключевых аспектов, на которые стоит обращать внимание:
Если смотреть через эти аспекты, многие проблемы легко диагностировать. Нестабильные результаты – проверяйте порядок загрузки контекста, дело не в модели; автоматизация выходит из-под контроля – проверяйте уровень управления, не «агент слишком активный»; качество длинных сессий падает – промежуточные артефакты загрязнили контекст, начать новую сессию полезнее, чем бесконечно подкручивать промпт.
2. Границы понятий: MCP / Plugin / Tools / Skills / Hooks / Subagents
Простое запоминание:
новые возможности для Claude – Tool/MCP,
набор рабочих методов – Skill,
изолированная среда выполнения – Subagent,
принудительные ограничения и аудит – Hook,
распространение между проектами – Plugin.
3. Контекстная инженерия: главное системное ограничение
Многие воспринимают контекст как «проблему ёмкости», но обычно затык не в том, что контекст слишком короткий, а в том, что он слишком зашумлён – полезная информация тонет в массе нерелевантного содержимого.
Реальная структура затрат на контекст
200K контекста Claude Code доступны не полностью:
200K Общий контекст ├── Фиксированные затраты (~15-20K) │ ├── Системные инструкции: ~2K │ ├── Дескрипторы всех включённых Skills: ~1-5K │ ├── Определения инструментов MCP Server: ~10-20K ← Главный скрытый убийца │ └── Состояние LSP: ~2-5K │ ├── Полуфиксированные (~5-10K) │ ├── CLAUDE.md: ~2-5K │ └── Memory: ~1-2K │ └── Динамически доступные (~160-180K) ├── История диалога ├── Содержимое файлов └── Результаты вызовов инструментов
Типичный MCP Server (например, GitHub) содержит 20-30 определений инструментов, каждое около 200 токенов, итого 4 000-6 000 токенов. Подключите 5 серверов, и одни только фиксированные расходы составят 25 000 токенов (12,5%). Когда я впервые подсчитал это число, был удивлён, что так много – при сценариях с чтением большого количества кода эти 12,5% действительно критичны.
Рекомендуемая слоистость контекста
Всегда резидентный → CLAUDE.md: контракт проекта / команды сборки / запреты По пути загрузки → rules: правила для языков / директорий / типов файлов По требованию → Skills: рабочие процессы / доменные знания Изолированная загрузка → Subagents: массовое исследование / параллельные изыскания Вне контекста → Hooks: детерминированные скрипты / аудит / блокировка
Проще говоря, то, что используется изредка, не нужно загружать каждый раз.
Лучшие практики работы с контекстом
Держите CLAUDE.md коротким, жёстким и исполнимым, приоритет – команды, ограничения, архитектурные границы. Официальный CLAUDE.md самого Anthropic занимает примерно 2,5K токенов – можно ориентироваться на это
Крупные справочные документы выносите в supporting files для Skills, не засовывайте в тело SKILL.md
Используйте
.claude/rules/для правил по путям/языкам, не перегружайте корневой CLAUDE.mdВ длинных сессиях активно используйте
/contextдля мониторинга расхода, не ждите автоматического сжатия
При смене задачи приоритет –
/clear, при переходе к новому этапу той же задачи –/compactПропишите Compact Instructions в CLAUDE.md – что сохранять при сжатии, контролируете вы, а не алгоритм
Шум Tool Output: ещё один скрытый убийца контекста
Выше мы посчитали фиксированные расходы на определения инструментов MCP, но в динамической части тоже есть ловушка, которую легко не заметить – Tool Output. Один полный вывод cargo test может занять тысячи строк, git log, find, grep в чуть более крупном репозитории тоже легко забивают экран. Claude не нужно видеть всё это целиком, но пока оно в контексте – это реальный расход токенов, который вытесняет историю диалога и содержимое файлов.
Позже я увидел подход RTK (Rust Token Killer) и подумал, что идея правильная: он автоматически фильтрует вывод команд до того, как они попадают к Claude, оставляя только ключевую информацию для принятия решений. Например, cargo test:
# Исходный вывод, который видит Claude running 262 tests test auth::test_login ... ok ...(тысячи строк) # После RTK ✓ cargo test: 262 passed (1 suite, 0.08s)
Claude реально нужно знать только «прошло или упало, и где упало», остальное – шум. RTK работает через Hook, прозрачно подменяя команды – для Claude Code совершенно незаметно. Проект открыт на GitHub.
Ловушка механизма сжатия
Алгоритм сжатия по умолчанию определяет приоритет по принципу «можно перечитать заново», поэтому ранний Tool Output и содержимое файлов удаляются первыми, а заодно выбрасываются и архитектурные решения с обоснованиями ограничений. Через два часа при повторном редактировании вы можете не помнить, что решили два часа назад, – и непонятные баги появляются именно так.
Решение – явно прописать в CLAUDE.md:
## Compact Instructions When compressing, preserve in priority order: - Architecture decisions (NEVER summarize) - Modified files and their key changes - Current verification status (pass/fail) - Open TODOs and rollback notes - Tool outputs (can delete, keep pass/fail only)
Помимо Compact Instructions есть более активный подход: перед открытием новой сессии попросить Claude написать HANDOFF.md – текущий прогресс, что пробовали, что сработало, что оказалось тупиком, что делать дальше. Следующий экземпляр Claude просто читает этот файл и продолжает, не полагаясь на качество сжатия алгоритмом.
Напиши в HANDOFF.md текущий прогресс. Объясни, что пробовал, что сработало, что нет, чтобы следующий агент со свежим контекстом мог просто прочитать этот файл и продолжить задачу.
После написания бегло просмотрите, если чего-то не хватает – попросите дополнить, затем откройте новую сессию и отправьте путь к HANDOFF.md.
Инженерная ценность Plan Mode
Суть Plan Mode – разделение исследования и выполнения: на этапе исследования файлы не трогаем, после подтверждения плана – выполняем:
Этап исследования – преимущественно операции только для чтения
Claude может сначала уточнить цели и границы, а затем предложить конкретный план
Затраты на выполнение возникают только после подтверждения плана
Для сложного рефакторинга, миграций и межмодульных изменений это гораздо полезнее, чем «скорее писать код» – значительно снижается вероятность уйти по ложному пути. Нажмите дважды Shift+Tab для входа в Plan Mode.
Продвинутый приём – открыть один Claude для написания плана, а другой Codex в роли «старшего инженера» для ревью этого плана. AI проверяет AI – работает отлично.
4. Проектирование Skills: не библиотека шаблонов, а подгружаемый по требованию рабочий процесс
Официальное описание Skill – «знания и рабочие процессы, подгружаемые по запросу». Дескриптор постоянно находится в контексте, полное содержимое загружается по требованию – это сильно отличается от «сохранённого промпта».
Чему должен соответствовать хороший Skill
Описание должно сообща��ь модели «когда меня использовать», а не «что я делаю» – разница огромна
Должны быть полные шаги, входные данные, выходные данные и условия остановки, а не только начало без конца
В основном тексте – только навигация и ключевые ограничения, объёмные материалы выносите в supporting files
Skill с побочными эффектами должен иметь явную настройку
disable-model-invocation: true, иначе Claude будет сам решать, запускать его или нет
Как Skill реализует подгрузку по требованию
Команда Claude Code в своём внутреннем дизайне неоднократно подчёркивала концепцию «progressive disclosure» (прогрессивное раскрытие) – идея не в том, чтобы модель видела всю информацию сразу, а в том, чтобы сначала получить индекс и навигацию, а затем подтягивать детали по необходимости:
SKILL.md определяет семантику задачи, границы и скелет выполнения
Supporting files предоставляют доменные детали
Скрипты детерминированно собирают контекст или доказательства
Стабильная структура выглядит так:
.claude/skills/ └── incident-triage/ ├── SKILL.md ├── runbook.md ├── examples.md └── scripts/ └── collect-context.sh
Три типичных типа Skills
Тип 1: Чеклист (качественный барьер)
Прогон перед релизом, чтобы ничего не пропустить:
--- name: release-check description: Use before cutting a release to verify build, version, and smoke test. --- ## Pre-flight (All must pass) - `cargo build --release` passes - `cargo clippy -D warnings` clean - Version bumped in Cargo.toml - CHANGELOG updated - `kaku doctor` passes on clean env ## Output Pass / Fail per item. Any Fail must be fixed before release.
Тип 2: Рабочий процесс (стандартизированная операция)
Миграция конфигурации – высокий риск, явный вызов + встроенные шаги отката:
--- name: config-migration description: Migrate config schema. Run only when explicitly requested. disable-model-invocation: true --- ## Steps 1. Backup: `cp ~/.config/kaku/config.toml ~/.config/kaku/config.toml.bak` 2. Dry run: `kaku config migrate --dry-run` 3. Apply: remove `--dry-run` after confirming output 4. Verify: `kaku doctor` all pass ## Rollback `cp ~/.config/kaku/config.toml.bak ~/.config/kaku/config.toml`
Тип 3: Доменный эксперт (инкапсулированная структура принятия решений)
При проблемах в рантайме Claude собирает доказательства по фиксированному пути, а не гадает:
--- name: runtime-diagnosis description: Use when kaku crashes, hangs, or behaves unexpectedly at runtime. --- ## Evidence Collection 1. Run `kaku doctor` and capture full output 2. Last 50 lines of `~/.local/share/kaku/logs/` 3. Plugin state: `kaku --list-plugins` ## Decision Matrix | Symptom | First Check | |---------------------|-------------------------------------| | Crash on startup | doctor output → Lua syntax error | | Rendering glitch | GPU backend / terminal capability | | Config not applied | Config path + schema version | ## Output Format Root cause / Blast radius / Fix steps / Verification command
Сокращайте дескрипторы – каждый Skill отъедает контекстное пространство. Разница до и после оптимизации значительна:
# Неэффективно (~45 tokens) description: > This skill helps you review code changes in Rust projects. It checks for common issues like unsafe code, error handling... Use this when you want to ensure code quality before merging. # Эффективно (~9 tokens) description: Use for PR reviews with focus on correctness.
Важная стратегия использования disable-auto-invoke:
Высокая частота (>1 раз/сессия) → оставить auto-invoke, оптимизировать дескриптор
Низкая частота (<1 раз/сессия) → disable-auto-invoke, ручной запуск, дескриптор полностью исключён из контекста
Крайне низкая частота (<1 раз/месяц) → удалить Skill, перенести в документацию AGENTS.md
Антипаттерны Skills
Описание слишком короткое:
description: help with backend(срабатывает на любую бэкенд-работу, ха-ха)Основной текст слишком длинный: сотни строк рабочей инструкции целиком в SKILL.md
Один Skill покрывает review, deploy, debug, docs, incident – пять задач сразу
Skill с побочными эффектами допускает автоматический вызов моделью
5. Проектирование инструментов: как помочь Claude реже ошибаться с выбором
Чем дольше я пользуюсь, тем больше убеждаюсь: инструменты для Claude и API для людей – это разные вещи. API для людей стремится к полноте функций, но для агента главное – не «насколько полный набор возможностей», а «насколько легко использовать правильно».
Хорошие инструменты vs Плохие инструменты
Несколько практических принципов проектирования:
Префикс имени по системе или ресурсу:
github_pr_*,jira_issue_*Поддержка
response_format: concise / detailedдля больших ответовОшибки должны учить модель, как исправиться, а не просто выдавать непрозрачный error code
Если можно объединить в высокоуровневый инструмент задачи – не выставляйте множество низкоуровневых фрагментов, избегайте
list_all_*, заставляющих модель самостоятельно фильтровать
Что можно узнать из эволюции внутренних инструментов Claude Code
Когда я увидел историю эволюции внутренних инструментов команды Claude Code, мне показалось это весьма любопытным. Для сценария, когда нужно остановиться посреди задачи и спросить пользователя, они попробовали три подхода:
Версия 1: добавить параметр
questionк существующему инструменту (например, Bash), чтобы Claude попутно задавал вопрос. Результат – Claude в большинстве случаев игнорировал этот параметр и продолжал работу, вообще не останавливаясь.Версия 2: требовать от Claude специальный markdown-формат в выводе, внешний парсер останавливал выполнение при его обнаружении. Проблема – нет жёсткого ограничения, Claude часто «забывал» писать в нужном формате, логика вопросов была очень хрупкой.
Версия 3: сделать отдельный инструмент AskUserQuestion. Хочешь спросить – явно вызови его, вызов = пауза, никакой двусмысленности, гораздо надёжнее предыдущих версий.
Схема ниже хорошо объясняет, почему третья версия значительно стабильнее:
Левая часть (свободный markdown-вывод) – слишком расслаблено, формат произвольный, парсинг хрупкий; правая часть (параметр ExitPlanTool) – слишком жёстко, вопрос можно задать только при выходе из этапа планирования, что слишком поздно; AskUserQuestion как отдельный инструмент – посередине, структурированный и вызываемый в любой момент – самый стабильный из трёх.
Проще говоря: если вам нужно, чтобы Claude остановился и спросил – дайте ему специальный инструмент для этого. Флаг или соглашение о формате вывода он часто проскакивает мимоходом.
Эволюция инструмента Todo
Раньше использовали инструмент TodoWrite + напоминание каждые 5 ходов, чтобы Claude помнил задачу. По мере усиления модели этот инструмент стал ограничением – напоминания Todo заставляли Claude думать, что нужно строго следовать, не давая гибко корректировать план. Интересный урок: инструмент добавили потому, что модель была недостаточно сильной, а когда модель стала сильнее – он превратился в оковы. Стоит периодически возвращаться и проверять, актуальны ли старые ограничения.
Эволюция инструмента поиска: изначально использовали RAG с векторной базой данных – быстро, но требует индексации, хрупко в разных окружениях, и главное – Claude не любил его использовать. Переход на инструмент Grep, позволяющий Claude искать самостоятельно, оказался гораздо удобнее. Позже обнаружился дополнительный бонус: Claude читает файл Skill, файл Skill ссылается на другие файлы, модель рекурсивно их читает, обнаруживая информацию по мере необходимости – не нужно заранее впихивать всё. Этот паттерн потом назвали «прогрессивным раскрытием».
Когда НЕ стоит добавлять инструмент:
Локальный shell может надёжно справиться с задачей
Модели нужны только статические знания, реальное взаимодействие с внешним миром не требуется
Потребность больше подходит для рабочего процесса Skill, а не для возможностей инструмента Tool
Описание инструмента, схема и формат возврата ещё не проверены на стабильное использование моделью
6. Hooks: принудительная вставка вашей логики до и после действий Claude
Hooks легко принять за «автоматически запускаемые скрипты», но по моему опыту они больше похожи на возврат в детерминированный процесс тех вещей, которые нельзя доверять Claude решать на лету.
Например, запускать ли форматирование, можно ли изменять защищённые файлы, отправлять ли уведомление после завершения задачи – не стоит надеяться, что Claude каждый раз об этом вспомнит.
Текущие поддерживаемые точки Hook:
Что подходит и не подходит для Hooks
Подходит: блокировка изменений защищённых ф��йлов, автоформатирование/lint/лёгкая проверка после Edit, инъекция динамического контекста при SessionStart (Git-ветка, переменные окружения), push-уведомление после завершения задачи.
Не подходит: сложные семантические суждения, требующие большого контекста, длительные бизнес-процессы, решения, требующие многоступенчатого рассуждения и взвешивания – для этого есть Skill или Subagent.
{ "hooks": { "PostToolUse": [ { "matcher": "Edit", "pattern": "*.rs", "hooks": [{ "type": "command", "command": "cargo check 2>&1 | head -30", "statusMessage": "Running cargo check..." }] }, { "matcher": "Notification", "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Task completed\" with title \"Claude Code\"'" }] } ] } }
Hooks: чем раньше обнаружена ошибка, тем больше экономия времени
В сессии со 100 правками экономия 30-60 секунд на каждой даёт 1-2 часа суммарно – весьма ощутимо.
Обратите внимание на ограничение длины вывода (| head -30) – иначе вывод Hook сам загрязнит контекст. Если не хотите вручную добавлять обрезку к каждой команде, посмотрите на RTK из раздела 3 – он систематизирует этот процесс.
Трёхуровневая комбинация: Hooks + Skills + CLAUDE.md
CLAUDE.md: декларация «перед коммитом обязательно пройти тесты и lint»
Skill: инструкция для Claude – в каком порядке запускать тесты, как интерпретировать ошибки, как исправлять
Hook: жёсткая проверка критических путей, при необходимости – блокировка
По опыту, без любого из трёх слоёв остаются дыры. Только правила в CLAUDE.md – Claude часто их игнорирует; только Hooks – тонкие суждения не покрыть. Вместе – значительно стабильнее.
7. Subagents: отправьте независимого Claude на конкретную задачу
Subagent – это независимый экземпляр Claude, порождённый из основного диалога, с собственным контекстным окном, использующий только указанные вами инструменты, после завершения отчитывающийся о результатах. По моему опыту, главная ценность – не «параллелизм», а изоляция. Сканирование кодовой базы, запуск тестов, проведение ревью – всё это генерирует огромный объём вывода. Если засунуть это в основной поток, полезный контекст быстро вытеснится. Передайте Subagent – основной поток получит только сводку, гораздо чище.
Claude Code имеет три встроенных: Explore (только чтение, по умолчанию на Haiku для экономии), Plan (планирование и исследование), General-purpose (универсальный), плюс можно создавать свои.
При конфигурации – явные ограничения
tools / disallowedTools: ограничьте доступные инструменты, не давайте те же широкие права, что у основного потокаmodel: для исследовательских задач – Haiku/Sonnet, для важного ревью – OpusmaxTurns: защита от убеганияisolation: worktree: изоляция файловой системы при необходимости модификации файлов
Ещё полезная деталь: долго работающие bash-команды можно отправить в фон по Ctrl+B, Claude потом проверит результат через BashOutput, не блокируя продолжение работы основного потока. С subagent аналогично – просто скажите «запустить в фоне».
Несколько типичных антипаттернов
Права дочернего агента такие же широкие, как у основного потока – изоляция теряет смысл
Формат вывода не зафиксирован – основной поток не может использовать результат
Подзадачи сильно зависят друг от друга и часто обмениваются промежуточным состоянием – в таком случае Subagent не подходит
8. Prompt Caching: ядро внутренней архитектуры Claude Code
Этот аспект я раньше не встречал развёрнуто в обучающих материалах, но он серьёзно влияет на структуру затрат Claude Code и многие проектные решения.
В инженерии есть фраза «Cache Rules Everything Around Me» – для агентов это тоже верно. Вся архитектура Claude Code построена вокруг Prompt-кэширования. Высокая частота попаданий не только экономит деньги – ограничения по скорости тоже смягчаются. Anthropic даже настроили алерты на частоту попаданий – при слишком низкой объявляется SEV (инцидент).
Структура промпта, спроектированная для кэширования
Prompt-кэш работает по принципу сопоставления префиксов – от начала запроса до каждой точки cache_control всё кэшируется. Поэтому порядок важен:
Порядок промпта Claude Code: System Prompt → статический, заблокирован Tool Definitions → статические, заблокированы Chat History → динамический, идёт дальше Текущий ввод → самый последний
Частые ловушки, ломающие кэш:
Временные метки в статическом системном промпте (делают его разным каждый раз)
Недетерминированная перетасовка порядка определений инструментов
Добавление/удаление инструментов посреди сессии
А как быть с динамической информацией вроде текущего времени? Не трогайте системный промпт – передавайте в следующем сообщении. Claude Code сам так делает – добавляет тег <system-reminder> в пользовательском сообщении, системный промпт не меняется, кэш не ломается.
Не переключайте модель посреди сессии
Prompt-кэш привязан к конкретной модели. Если вы уже наговорили 100K токенов с Opus и хотите задать простой вопрос, переключение на Haiku фактически обойдётся дороже, чем продолжение на Opus, потому что придётся перестроить весь кэш для Haiku. Если действительно нужно переключиться – используйте Subagent: Opus готовит «сообщение-передачу» для другой модели с описанием задачи.
Реальная реализация Compaction
Схема выше показывает процесс Compaction (сжатие контекста): слева – состояние при почти заполненном контексте; посередине – Claude Code делает fork-вызов, передаёт полную историю диалога модели с указанием «Summarize this conversation», этот шаг попадает в кэш и стоит всего 1/10 цены; справа – после сжатия десятки раундов диалога заменяются сводкой ~20K токенов, System + Tools остаются, подключаются ранее использованные ссылки на файлы, освобождая место для новых раундов.
Интуитивно Plan Mode должен переключаться на набор инструментов только для чтения, но это сломает кэш. Реальная реализация: EnterPlanMode – это инструмент, который модель может вызвать сама, обнаружив сложную проблему, входя в plan mode самостоятельно. Набор инструментов не меняется – кэш не затрагивается.
defer_loading: отложенная загрузка инструментов
Claude Code имеет десятки MCP-инструментов, полное включение каждый запрос – дорого, но удаление посреди сессии ломает кэш. Решение – отправлять лёгкий stub с только именем инструмента, помеченный defer_loading: true. Модель «обнаруживает» их через инструмент ToolSearch, полная схема загружается только после выбора моделью – кэш-префикс остаётся стабильным.
9. Замкнутый цикл верификации: без Verifier нет инженерного агента
«Claude сказал, что готово» – по сути бесполезно. Нужно иметь возможность узнать, сделано ли правильно, откатить при проблеме и проверить процесс – вот тогда это считается.
Уровни верификации
Нижний уровень: код возврата команды, lint, typecheck, unit test
Средний уровень: интеграционные тесты, сравнение скриншотов, contract test, smoke test
Верхний уровень: проверка production-логов, метрики мониторинга, чеклист ручного ревью
Явно определяйте верификацию в промптах, Skills и CLAUDE.md:
## Verification - For backend changes: Run `make test` and `make lint` - For API changes: update contract tests under `tests/contracts/` - For UI changes: Capture before/after screenshots if visual - Definition of done: - All tests pass - Lint passes - No TODO left behind unless explicitly tracked
При написании промптов задач или Skills лучше заранее описать критерии приёмки: какие команды выполнить для завершения, что проверить при ошибке, что увидеть на скриншотах и в логах – чем раньше это проговорено, тем меньше проблем потом.
У меня есть простое правило: если вы не можете объяснить «как понять, что Claude сделал правильно», то задача, скорее всего, не подходит для полностью автоматического выполнения Claude.
10. Инженерное значение часто используемых команд
Эти команды по сути делают одно: активно управляют контекстом, не дожидаясь автоматической обработки системой.
Управление контекстом
/context # Посмотреть структуру расхода токенов, диагностировать MCP и чтение файлов /clear # Очистить сессию. Если вас поправляли больше двух раз – начинайте заново /compact # Сжать, сохранив важное, в связке с Compact Instructions /memory # Проверить, какие CLAUDE.md действительно загружены
Возможности и управление
/mcp # Управление MCP-соединениями, проверка стоимости токенов, отключение простаивающих серверов /hooks # Управление hooks, точка входа в уровень управления /permissions # Просмотр или обновление белого списка разрешений /sandbox # Настройка изоляции песочницы, обязательно для высокой автоматизации /model # Переключение модели: Opus для глубокого рассуждения, Sonnet для обычных задач, Haiku для быстрого исследования
Непрерывность сессий и параллелизм
claude --continue # Возобновить последнюю сессию в текущей директории, продолжить на следующий день claude --resume # Открыть селектор для восстановления из истории сессий claude --continue --fork # Форк от существующей сессии, одна отправная точка – разные подходы claude --worktree # Создать изолированный git worktree claude -p "prompt" # Неинтерактивный режим, интеграция в CI / pre-commit / скрипты claude -p --output-format json # Структурированный вывод для скриптов
Несколько менее известных, но очень полезных команд
/simplify: трёхмерная проверка только что изменённого кода – переиспользование, качество и эффективность, найденные проблемы исправляются сразу. Особенно полезно запускать сразу после изменения логики, заменяет ручное ревью.
/rewind: не «отмена», а возврат к определённому checkpoint сессии для повторного резюмирования. Подходит когда Claude зашёл слишком далеко по ошибочному пути, или нужно сохранить консенсус первой половины, отбросив неудачную вторую.
/btw: быстрый побочный вопрос без прерывания основной задачи. Подходит для «в чём разница между двумя командами» – однораундовые побочные ответы. Не подходит для вопросов, требующих чтения репозитория или вызова инструментов.
claude -p --output-format stream-json: поток JSON-событий в реальном времени, для мониторинга длительных задач, инкрементальной обработки, потоковой интеграции в свои инструменты.
/insight: Claude анализирует текущую сессию и выделяет, что стоит закрепить в CLAUDE.md. Запускайте после некоторого времени работы – укажет на «это соглашение вы обсуждали много раз, но не записали в контракт» и подобные слепые зоны. Отличный инструмент для итеративной оптимизации CLAUDE.md.
Двойное нажатие ESC для возврата: два нажатия ESC позволяют вернуться к предыдущему вводу и отредактировать его. Claude ушёл не туда или предыдущая фраза была неточной – двойной ESC, правка и повторная отправка, гораздо экономнее новой сессии.
История диалогов хранится локально: все записи сессий находятся в ~/.claude/projects/, папки именуются по пути проекта (слеши заменены дефисами), каждая сессия – файл .jsonl. Чтобы найти историю по теме – grep -rl "ключевое слово" ~/.claude/projects/, или просто скажите Claude «поищи мне предыдущее обсуждение X» – он сам найдёт.
11. Как написать хороший CLAUDE.md
CLAUDE.md, на мой взгляд, – это договор о сотрудничестве между вами и Claude, а не командная документация и не база знаний. Здесь только то, что должно выполняться в каждой сессии.
Мой совет прост: в начале можно даже ничего не писать. Начните пользоваться, и когда заметите, что постоянно повторяете одно и то же – добавьте это. Добавлять нетрудно: введите # чтобы дополнить CLAUDE.md содержимым текущего диалога, или просто скажите Claude «добавь это в CLAUDE.md проекта» – он знает, какой файл редактировать.
Что должно быть
Как собирать, как тестировать, как запускать (самое главное)
Ключевая структура директорий и границы модулей
Стиль кода и соглашения по именованию
Неочевидные подводные камни окружения
Список абсолютных запретов (NEVER)
Информация, обязательная к сохранению при сжатии (Compact Instructions)
Чего быть не должно
Длинные вводные описания
Полная API-документация
Абстрактные принципы вроде «пиши качественный код»
Очевидная информация, которую Claude может определить, прочитав репозиторий
Объёмные справочные материалы и знания для редких задач (это для Skills)
Качественный шаблон
# Project Contract ## Build And Test - Install: `pnpm install` - Dev: `pnpm dev` - Test: `pnpm test` - Typecheck: `pnpm typecheck` - Lint: `pnpm lint` ## Architecture Boundaries - HTTP handlers live in `src/http/handlers/` - Domain logic lives in `src/domain/` - Do not put persistence logic in handlers - Shared types live in `src/contracts/` ## Coding Conventions - Do not introduce new global state without explicit justification - Reuse existing error types from `src/errors/` ## Safety Rails ### NEVER - Modify `.env`, lockfiles, or CI secrets without explicit approval - Remove feature flags without searching all call sites - Commit without running tests ### ALWAYS - Show diff before committing - Update CHANGELOG for user-facing changes ## Verification - Backend changes: `make test` + `make lint` - API changes: update contract tests under `tests/contracts/` - UI changes: capture before/after screenshots ## Compact Instructions Preserve: - Architecture decisions (NEVER summarize) - Modified files and key changes - Current verification status (pass/fail commands) - Open risks, TODOs, rollback notes
Использование несложное: то, что нужно знать ка��дый раз – CLAUDE.md, что действует только для части файлов – rules, что нужно только для определённого типа задач – Skills.
Пусть Claude сам поддерживает свой CLAUDE.md
Мой любимый приём: после каждого исправления ошибки Claude – попросить его самого обновить CLAUDE.md:
«Обнови свой CLAUDE.md, чтобы не повторять эту ошибку.»
Claude довольно хорошо дополняет такие правила для себя, со временем одинаковые ошибки действительно случаются реже. Но периодическое ревью необходимо – со временем некоторые записи устаревают, ограничения, полезные ранее, могут стать неактуальными. Более систематический подход описан в разделе 14.
12. Свежий опыт из недавних экспериментов
Во время новогодних каникул я сделал с помощью Claude Code открытый терминальный проект Kaku – на базе Rust + Lua, с некоторыми AI-возможностями. Смешанные языки плюс кастомная система конфигурации выявили немало типичных проблем агентного взаимодействия. Поделюсь несколькими наиболее полезными уроками.
Прозрачность окружения важнее, чем кажется
Claude Code вызывает реальные shell, git, package manager и локальные конфигурации. Если хоть один слой непрозрачен – модель начинает гадать, а с гаданием надёжность падает. Это не уникальная проблема Claude Code – у многих агентов то же самое.
Поэтому я довольно быстро добавил в терминал команду doctor, которая собирает состояние окружения, зависимости и конфигурацию в единый структурированный отчёт о здоровье. Claude Code запускает doctor перед началом работы – это реально экономит время на проблемах «начал работать, не разобравшись с окружением».
Ещё я обнаружил, что если CLI имеет семантически понятные подкоманды вроде init, config, reset, Claude Code работает значительно стабильнее, чем когда нужно самому угадывать расположение конфигурационных файлов. Сначала привести состояние к порядку, потом предоставить точку входа для редактирования – если порядок обратный, легко получить хаос.
Практика Hooks для проекта со смешанными языками
Два языка, две проверки – отлично подходит для Hooks с триггерами по типу файла:
{ "hooks": { "PostToolUse": [ { "matcher": "Edit", "pattern": "*.rs", "hooks": [{ "type": "command", "command": "cargo check 2>&1 | head -30", "statusMessage": "Checking Rust..." }] }, { "matcher": "Edit", "pattern": "*.lua", "hooks": [{ "type": "command", "command": "luajit -b $FILE /dev/null 2>&1 | head -10", "statusMessage": "Checking Lua syntax..." }] } ] } }
Сразу узнать об ошибке компиляции после каждого редактирования – гораздо приятнее, чем «наделал кучу правок и обнаружил, что ещё первая была сломана».
Полный эталонный инженерный лейаут
Если хотите настроить полноценную инженерную структуру Claude Code для своего проекта, вот образец. Не обязательно делать всё – адаптируйте по потребностям:
Project/ ├── CLAUDE.md ├── .claude/ │ ├── rules/ │ │ ├── core.md │ │ ├── config.md │ │ └── release.md │ ├── skills/ │ │ ├── runtime-diagnosis/ # Сбор логов, состояния и зависимостей │ │ ├── config-migration/ # Миграция конфигурации с защитой от повреждений │ │ ├── release-check/ # Предрелизная проверка, smoke test │ │ └── incident-triage/ # Сортировка production-инцидентов │ ├── agents/ │ │ ├── reviewer.md │ │ └── explorer.md │ └── settings.json └── docs/ └── ai/ ├── architecture.md └── release-runbook.md
Глобальные ограничения (CLAUDE.md), ограничения по путям (rules), рабочие процессы (skills) и архитектурные детали – каждому своё место, Claude Code будет работать значительно стабильнее. Если вы ведёте несколько проектов одновременно, стабильный личный базис можно положить в ~/.claude/, а различия по проектам – в проектный .claude/, синхронизируя скриптом, чтобы проекты не загрязняли друг друга.
13. Типичные антипаттерны
14. Проверка здоровья конфигурации
На основе шестислойной модели из статьи я оформил эту проверку в открытый Skill-проект tw93/claude-health, который позволяет одной командой проверить текущее состояние конфигурации Claude Code.
npx skills add tw93/claude-health
После установки запустите /health в любой сессии – он автоматически определит сложность проекта и проверит CLAUDE.md, rules, skills, hooks, allowedTools и реальные паттерны поведения, выдав приоритизированный отчёт: нужно исправить немедленно / структурные проблемы / можно делать постепенно.
Если после прочтения этой статьи хотите узнать, насколько ваша конфигурация далека от этих принципов – запустите /health, это самый быстрый способ.
15. Заключение
Работа с Claude Code проходит примерно через три стадии:
На третьей стадии фокус незаметно смещается: с «как использовать эту функцию» на «как заставить агента работать самостоятельно в рамках ограничений» – ощущается совсем по-другому.
Есть один вопрос, над которым стоит задуматься: если вы не можете чётко сформулировать «что значит "готово"», то задача, скорее всего, не подходит для полностью автономного выполнения Claude. Если нет даже критериев проверки, Claude, каким бы умным он ни был, не сможет получить правильный ответ.
Это итоги полугода экспериментов. Наверняка есть ещё много неисследованного – если у вас есть более продвинутые техники, буду рад узнать.
