Краткое изложение: Хуки Claude Code — это скрипты автоматизации, которые выполняются в определенные моменты жизненного цикла сеансов кодирования ИИ, позволяя разработчикам выполнять пользовательские команды, проверять действия, форматировать код, отправлять уведомления и применять правила проекта. Эти хуки интегрируются в рабочий процесс Claude через такие события, как SessionStart, PreToolUse и PostToolUse, поддерживая модели выполнения на основе команд, HTTP и подсказок с настраиваемыми тайм-аутами и поведением кодов выхода.
Система хуков Claude Code превращает ИИ-ассистента для кодирования из полезного инструмента в полностью автоматизированную среду разработки. Большинство разработчиков не осознают степень контроля, доступного через хуки.
Однако дело вот в чем: хуки — это не просто выполнение скриптов после редактирования файлов. Они предоставляют точки перехвата на протяжении всего процесса принятия решений Claude. Прежде чем он выполнит команду. После сбоя вызова инструмента. Когда ему требуется разрешение. Даже до обработки пользовательских подсказок.
Это руководство охватывает все, что представлено в официальной документации, а также практические шаблоны, которые, как показывают обсуждения в сообществе, действительно работают в производственных средах.
Что на самом деле делают хуки Claude Code
Согласно официальной документации Claude Code, хуки — это пользовательские shell-команды, HTTP-конечные точки или инъекции подсказок, которые выполняются в определенные моменты жизненного цикла Claude Code. Они получают структурированный JSON-ввод через stdin и контролируют рабочий процесс через коды выхода или HTTP-ответы.
Автоматизация идет глубже, чем предполагают большинство руководств. Хуки могут полностью блокировать выполнение инструментов, вводить дополнительный контекст в рассуждения Claude, запускать внешние службы и применять правила проверки, которые Claude должен соблюдать.
Существует три основных типа хуков:
- Хуки команд: Shell-скрипты, которые общаются через stdout, stderr и коды выхода.
- HTTP-хуки: Удаленные конечные точки, которые получают POST-запросы и возвращают JSON-ответы.
- Хуки подсказок: Динамические инструкции, вводимые в контекст Claude при определенных событиях.
Каждый тип служит разным шаблонам автоматизации. Хуки команд обрабатывают локальную проверку и форматирование. HTTP-хуки интегрируются с внешними службами и базами данных. Хуки подсказок изменяют поведение Claude без внешних процессов.
Жизненный цикл хуков и система событий
Официальная документация определяет несколько событий хуков (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification и другие), которые срабатывают во время выполнения Claude Code. Понимание того, когда срабатывает каждое из них, определяет возможную автоматизацию.
| Событие | Когда срабатывает | Может блокировать |
|---|---|---|
| SessionStart | Когда сеанс начинается или возобновляется | Нет |
| UserPromptSubmit | Когда вы отправляете подсказку, до ее обработки Claude | Да |
| PreToolUse | Перед выполнением вызова инструмента | Да |
| PermissionRequest | Когда появляется диалоговое окно разрешения | Да |
| PostToolUse | После успешного вызова инструмента | Нет |
| PostToolUseFailure | После сбоя вызова инструмента | Нет |
| Notification | Когда Claude Code отправляет уведомление | Нет |
| SubmitMessage | Когда Claude отправляет сообщение пользователю | Нет |
| ContextCompaction | Когда окно контекста приближается к пределам | Нет |
Возможность блокировки имеет наибольшее значение. Хуки PreToolUse могут предотвратить опасные операции до их выполнения. Код выхода 1 блокирует действие. Код выхода 0 разрешает его. Код выхода 2 побуждает Claude пересмотреть.
Но подождите. Хуки PostToolUse не могут отменить действия, поскольку инструмент уже выполнен. Это ограничение формирует структуру логики проверки. Критические проверки принадлежат PreToolUse. Очистка и форматирование принадлежат PostToolUse.
Просматривайте предложения AI Tool Perks при настройке Claude Code
Если вы работаете с хуками Claude Code, вы также можете выбирать другие инструменты ИИ для вашего рабочего процесса. Get AI Perks собирает стартовые кредиты и скидки на программное обеспечение для ИИ и облачных инструментов в одном месте. Платформа включает более 200 предложений с условиями получения бонусов и руководствами по их оформлению для каждого из них.
Ищете бонусы Claude или других инструментов ИИ?
Проверьте Get AI Perks, чтобы:
- просматривать предложения Claude и других инструментов ИИ
- сравнивать условия получения бонусов перед подачей заявки
- находить стартовые скидки на весь стек инструментов
👉 Посетите Get AI Perks, чтобы изучить текущие предложения программного обеспечения для ИИ.
Конфигурация и структура файлов
Хуки определяются в файле .claude/settings.json в проекте. Схема конфигурации поддерживает глобальные хуки и сопоставления, специфичные для инструментов, которые фильтруют, когда хуки выполняются.
Базовая структура хука команды:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
Переменная ${file} разворачивается в фактический путь к файлу из входных данных инструмента. Согласно официальной документации, хуки поддерживают такие раскрытия переменных в полях command и args.
Иерархия расположения хуков
Claude Code проверяет несколько расположений для определений хуков с четким порядком приоритета:
- На уровне проекта: .claude/settings.json в текущем рабочем пространстве
- На уровне пользователя: ~/.claude/settings.json для всех сеансов
- Предоставляется плагинами: Хуки, поставляемые с установленными плагинами
Хуки проекта переопределяют хуки пользователя для одного и того же события. Это позволяет использовать правила форматирования, специфичные для проекта, сохраняя при этом глобальные обработчики уведомлений.
Шаблоны сопоставления для избирательного выполнения
Система сопоставления фильтрует хуки для конкретных инструментов или условий. Без сопоставлений хуки срабатывают при каждом возникновении их события.
| { “hooks”: [ { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “src/**/*.ts” }, “command”: “./scripts/validate-typescript.sh” } ] } |
Поле pathPattern принимает синтаксис glob. Поле toolName сопоставляется со встроенными инструментами Claude, такими как edit_file, execute_command, read_file и create_directory.
Обсуждения в сообществе показывают, что комбинации сопоставлений работают по логике И. Все указанные сопоставления должны совпадать, чтобы хук выполнился.
Хуки команд: интеграция с Shell-скриптами
Хуки команд выполняют shell-команды или скрипты со структурированным JSON-вводом. Они представляют собой наиболее распространенный тип хуков для локальной автоматизации.
Официальная документация указывает, что хуки команд получают JSON через stdin со следующей структурой:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Скрипты парсят этот ввод для принятия решений. Хук проверки на Python может выглядеть так:#!/usr/bin/env python3 import sys import json input_data = json.load(sys.stdin) tool_input = input_data.get(‘toolInput’, {}) file_path = tool_input.get(‘path’, ”) if file_path.startswith(‘protected/’): print(“Cannot edit protected files”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Код выхода 0 разрешает операцию. Код выхода 1 блокирует ее и показывает сообщение stderr Claude. Код выхода 2 вызывает специальное поведение в зависимости от события.
Поведение кода выхода 2
Согласно официальной документации по хукам, код выхода 2 имеет значение, специфичное для события (PreToolUse: блокирует и предлагает пересмотр; UserPromptSubmit: предоставляет контекст без блокировки; PermissionRequest: блокирует разрешение):
- PreToolUse: Блокирует инструмент и предлагает Claude пересмотреть с сообщением stderr в качестве контекста.
- UserPromptSubmit: Предоставляет вывод stderr в качестве дополнительного контекста без блокировки.
- PermissionRequest: Блокирует предоставление разрешения.
Это создает промежуточное решение между жесткой блокировкой и разрешением. Claude получает обратную связь о том, почему действие может быть проблематичным, и может скорректировать свой подход.
Асинхронные хуки команд
Флаг async: true выполняет хуки в фоновом режиме, не блокируя рабочий процесс Claude. Это важно для медленных операций, таких как уведомления о развертывании или сбор метрик.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Когда срабатывает асинхронный хук, Claude Code запускает процесс и продолжает немедленно. Поле timeout устанавливает максимальное время выполнения в секундах. Если не указано, асинхронные хуки используют тайм-аут по умолчанию в 10 минут.
Реальность: асинхронные хуки не могут блокировать операции, поскольку они выполняются после того, как Claude продолжит. Они работают для логирования, уведомлений и очистки — не для проверки.
HTTP-хуки: Интеграция с внешними службами
HTTP-хуки отправляют JSON-полезные данные в удаленные конечные точки и разбирают ответы для управления принятием решений. Они обеспечивают интеграцию со службами проверки, базами данных и сторонними инструментами.
Базовая конфигурация HTTP-хука:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
Структура полезной нагрузки соответствует вводу хука команды, но поступает как тело HTTP POST. Ответ определяет следующее действие Claude.
Обработка HTTP-ответов
Согласно официальной документации, HTTP-хуки интерпретируют ответы на основе кода состояния и содержимого тела:
| Код состояния | Эффект | Источник сообщения |
|---|---|---|
| 200 | Разрешить операцию | Тело ответа (необязательно) |
| 400 | Заблокировать операцию | Тело ответа отображается Claude |
| 500 | Ошибка хука, разрешить операцию | Записано, но не отображается Claude |
| Другое | Разрешить операцию | Сбой хука не блокирует рабочий процесс |
Тело ответа может содержать поле сообщения, которое Claude видит как контекст. Это позволяет службам проверки объяснять, почему операция была заблокирована.
Интерполяция переменных среды
HTTP-хуки поддерживают синтаксис ${VAR} в полях url, headers и других строковых полях. Переменные раскрываются из среды, в которой работает Claude Code.
Согласно официальной документации MCP, раскрытие переменных среды включает синтаксис резервного значения по умолчанию: ${VAR:-default} раскрывается в VAR, если он установлен, в противном случае используется значение по умолчанию.
Ограничение безопасности: Согласно проблеме GitHub #28044, HTTP-хуки могут получить доступ только к переменным среды, явно перечисленным в поле конфигурации allowedEnvVars. Это предотвращает случайное раскрытие учетных данных.
Хуки подсказок: Впрыск контекста
Хуки подсказок впрыскивают динамические инструкции в контекст Claude при определенных событиях. Они изменяют поведение без внешних процессов или вызовов API.
| { “event”: “SessionStart”, “prompt”: “Вы работаете над проектом TypeScript. Всегда используйте строгие проверки на null и предпочитайте async/await перед promises.” } |
Введенный текст становится частью системных инструкций Claude для данного сеанса. Хуки подсказок также могут использовать шаблонные переменные, которые раскрываются на основе данных события.
Динамическая генерация подсказок
Согласно официальной документации, хуки подсказок поддерживают поля команд, которые генерируют динамические подсказки:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Команда получает стандартный JSON-ввод через stdin и выводит текст подсказки в stdout. Это позволяет генерировать контекстно-зависимые инструкции на основе состояния проекта.
Хуки агентов
Хуки агентов указывают под-агента, который обрабатывает событие, вместо прямой инъекции подсказки. Под-агент получает контекст о событии и может выполнять многошаговые рассуждения.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Вызов инструмента завершился неудачно. Проанализируйте ошибку и предложите исправления.” } |
Именованный под-агент должен быть определен в конфигурации проекта. Хуки агентов позволяют использовать сложную логику принятия решений, которую простая инъекция подсказок не может обеспечить.
Практические шаблоны хуков
Обсуждения в сообществе и официальные примеры раскрывают конкретные шаблоны автоматизации, которые надежно работают в производстве.
Автоматическое форматирование кода после редактирования
Наиболее распространенный шаблон автоматически форматирует код после того, как Claude редактирует файлы:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/*.{js,ts,jsx,tsx}” }, “command”: “prettier”, “args”: [“–write”, “${toolInput.path}”] } |
Переменная ${toolInput.path} разворачивается в путь отредактированного файла. PostToolUse гарантирует, что форматирование происходит после успешного редактирования, но не блокирует рабочий процесс Claude.
Блокировка модификации защищенных файлов
Хуки PreToolUse применяют правила защиты файлов:
| { “event”: “PreToolUse”, “matcher”: { “toolName”: “edit_file” }, “command”: “./scripts/check-protected.sh” } |
Скрипт проверяет целевой путь на соответствие защищенным шаблонам и завершается с кодом 1 для блокировки запрещенных правок.
Получать уведомления, когда Claude нуждается во вводе
Согласно официальному руководству по рабочему процессу, хуки Notification могут запускать настольные оповещения или отправлять сообщения внешним службам:
| { “event”: “Notification”, “command”: “osascript”, “args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””] } |
Это срабатывает каждый раз, когда Claude Code отправляет уведомление, в том числе при ожидании пользовательского ввода или после завершения задачи.
Повторный ввод контекста после уплотнения
Хуки ContextCompaction восстанавливают важный контекст, когда окно разговора заполняется:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “cat .claude/critical-context.md” } |
Вывод команды вводится обратно в контекст Claude после того, как уплотнение удалит старые сообщения. Это предотвращает потерю критически важных инструкций по проекту.
Аудит изменений конфигурации
Отслеживайте, когда Claude изменяет файлы конфигурации:
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “edit_file”, “pathPattern”: “**/{package.json,.env,*.config.*}” }, “command”: “git”, “args”: [“add”, “${toolInput.path}”], “async”: true } |
Асинхронное выполнение предотвращает блокировку Claude во время завершения операций git. Это создает аудиторский след изменений конфигурации без ручного стаджинга.
Вывод JSON и управление решениями
Хуки команд могут выводить структурированный JSON для предоставления подробной обратной связи, выходящей за рамки простых кодов выхода. Согласно официальному справочнику, вывод JSON обеспечивает многопольные ответы, которые Claude интерпретирует для принятия решений.
| { “allowed”: false, “message”: “Этот файл защищен политикой команды”, “suggestion”: “Создайте новый файл в src/features/ вместо этого” } |
Поле allowed контролирует, будет ли операция выполнена. Сообщение отображается Claude как контекст. Поле suggestion предоставляет альтернативные подходы.
Чтобы хуки выводили JSON, они должны:
- Записывать допустимый JSON в stdout
- Завершаться с кодом 0 (для разрешенных) или 1 (для заблокированных)
- Содержать как минимум булево поле allowed
Claude Code разбирает JSON и использует его для улучшения цикла обратной связи. Коды выхода по-прежнему определяют основное решение, но JSON предоставляет более богатый контекст.
Справочник по полям ввода хуков
Все хуки получают JSON-объект через stdin с общими полями и данными, специфичными для события. Понимание полной схемы позволяет создавать более сложные хуки.
Общие поля ввода
Каждый хук получает эти базовые поля:
- event: Название события хука (например, “PreToolUse”)
- sessionId: Уникальный идентификатор текущего сеанса Claude
- turnId: Идентификатор текущего хода разговора
- timestamp: Метка времени в формате ISO 8601, когда сработало событие
Поля события инструмента
События PreToolUse, PostToolUse и PostToolUseFailure включают:
- toolName: Название вызываемого инструмента (edit_file, execute_command и т. д.)
- toolInput: Объект, содержащий входные параметры инструмента
- toolResponse: Вывод инструмента (только PostToolUse)
- error: Детали ошибки, включая сообщение и код (только PostToolUseFailure)
Структура toolInput варьируется в зависимости от инструмента. Для edit_file она содержит path и content. Для execute_command она содержит command и args.
Поля события разрешения
События PermissionRequest включают:
- permissionType: Тип запрашиваемого разрешения (file_write, command_execute и т. д.)
- requestedAction: Конкретное действие, требующее разрешения
- resourcePath: Путь к файлу или идентификатор ресурса, на который оказывается воздействие
Хуки инструментов MCP
Согласно официальной документации по хукам, хуки могут сопоставляться с инструментами протокола контекста модели (MCP), используя поле сопоставления mcpTool. Это позволяет выполнять хуки, когда Claude использует внешние инструменты, предоставляемые серверами MCP.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
Значение mcpTool сопоставляется с именем инструмента в формате server-name/tool-name. Это позволяет использовать логику проверки для запросов к базам данных, вызовов API или других внешних операций.
Запросы на добавление функций в GitHub указывают на растущий интерес к более глубокой интеграции MCP, включая хуки, которые могут просматривать уведомления сервера MCP и реагировать на внешние события.
Соображения безопасности
Хуки выполняются с теми же правами, что и сам Claude Code. Это создает последствия для безопасности в многопользовательских средах и общих конфигурациях.
Песочница выполнения команд
Согласно проблеме GitHub #28044, HTTP-хуки маршрутизируются через прокси-сервер песочницы, который ограничивает сетевой доступ и фильтрует переменные среды. Командные хуки не имеют таких ограничений — они выполняются с полным доступом к оболочке.
Документация рекомендует следующие практики:
- Никогда не храните учетные данные в командах хуков
- Используйте переменные среды для конфиденциальных данных
- Проверяйте все входные данные из раскрытий ${...}
- Реализуйте ограничения тайм-аута для внешних служб
- Используйте асинхронные хуки для некритических операций, чтобы предотвратить блокировку при сбоях
Изоляция выполнения хуков
Хуки уровня пользователя в ~/.claude/settings.json применяются ко всем проектам. Это создает риски при работе с различными границами доверия. Хуки уровня проекта переопределяют хуки пользователя, но не могут полностью их отключить.
Меню /hooks в Claude Code показывает все активные хуки для текущего сеанса. Просмотр этого списка перед работой над конфиденциальными проектами помогает выявить потенциальные проблемы безопасности.
Отладка и устранение неполадок
Сбои хуков не всегда четко отображаются в диалоге Claude. Официальная документация предлагает несколько подходов к отладке.
Журналы выполнения хуков
Claude Code регистрирует выполнение хуков в выходных данных отладки сеанса. Согласно руководству по устранению неполадок, включение отладочного логирования выявляет:
- Какие хуки совпали для каждого события
- JSON-ввод, отправленный каждому хуку
- Вывод stdout и stderr из процессов хуков
- Коды выхода и время выполнения
- Коды и тела ответов HTTP для HTTP-хуков
Включите отладочное логирование, установив CLAUDE_DEBUG=1 в среде перед запуском Claude Code.
Самостоятельное тестирование хуков
Командные хуки можно тестировать вне Claude Code, вручную конструируя JSON-ввод:
| echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh |
Это проверяет логику хука, не запуская фактические операции Claude. Код выхода и вывод stdout/stderr должны соответствовать ожидаемому поведению.
Распространенные сбои хуков
Обсуждения в сообществе выявляют эти частые проблемы:
- Ошибки тайм-аута: Тайм-аут по умолчанию в 10 минут слишком короткий для медленных операций — увеличьте с помощью поля timeout.
- Сбои раскрытия путей: Переменные, такие как ${file}, неопределены для событий, которые не включают контекст файла.
- Ошибки разрешений: Скриптам хуков не хватает прав на выполнение — выполните chmod +x script.sh.
- Ошибки разбора JSON: Неправильный вывод JSON из хуков — проверьте с помощью jq перед возвратом.
- Недоступность переменных среды: Переменные не передаются процессу хука — проверьте среду Claude Code.
Влияние хуков на производительность
Синхронные хуки блокируют рабочий процесс Claude до завершения. Тайм-аут по умолчанию в 10 минут предотвращает бесконечные зависания, но даже короткие задержки накапливаются при множестве операций.
Практики сообщают, что простые хуки проверки оказывают незначительное влияние на производительность. Хуки форматирования файлов оказывают заметное, но приемлемое влияние на производительность. Вызовы внешних API могут вызвать трение в рабочем процессе. Сложные вычислительные операции выигрывают от асинхронного выполнения.
Пакетная обработка хуков
Несколько хуков могут соответствовать одному событию. Согласно справочной документации, хуки выполняются последовательно в порядке определения. Если какой-либо хук блокирует операцию, остальные хуки не выполняются.
Это важно для производительности. Пять синхронных хуков по 200 мс каждый добавляют одну секунду на событие. Объединение связанных проверок в один хук снижает накладные расходы.
Расширенные шаблоны
Помимо базовой автоматизации, хуки позволяют осуществлять сложную настройку рабочего процесса.
Цепочки хуков с сохранением состояния
Хуки могут сохранять состояние между выполнениями, используя файлы или базы данных. Хук PostToolUse может записывать успешные операции, которые хук PreToolUse затем проверяет:
| #!/bin/bash # Запись успешных правок echo “${toolInput.path}” >> .claude/edit-history.txt |
Сопутствующий хук PreToolUse может проверять эту историю, чтобы предотвратить избыточные операции или обеспечить соблюдение порядка.
Условная активация хуков
Переменные среды контролируют поведение хуков во время выполнения. Установка CLAUDE_SKIP_HOOKS=1 отключает хуки для экстренных ситуаций.
Сами хуки могут проверять флаги среды:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Применить строгую проверку exit 1 fi exit 0 |
Это позволяет использовать поведение режима разработки по сравнению с режимом производства без изменений конфигурации.
Многоступенчатая проверка
Хуки PreToolUse могут реализовывать многоуровневую проверку, где код выхода 2 позволяет Claude продолжить с предупреждениями:
- Жесткие сбои (код выхода 1): блокируют опасные операции.
- Мягкие предупреждения (код выхода 2): предупреждают Claude о необходимости пересмотра.
- Проход с контекстом (код выхода 0 + JSON): предоставление дополнительной информации.
Это создает спектр проверки, более тонкий, чем двоичное разрешение/запрет.
Интеграция с CI/CD
Согласно официальной документации по интеграции платформы, Claude Code работает в средах CI/CD для автоматизированного обзора кода и сортировки проблем. Хуки расширяют эту автоматизацию.
Рабочие процессы GitHub Actions могут определять хуки, которые применяют политики команды во время автоматизированных сеансов:
| – name: Запустить Claude Code со строгими хуками env: STRICT_MODE: 1 run: | claude “Проанализируйте этот PR и предложите улучшения” |
Флаг STRICT_MODE активирует условную логику проверки в скриптах хуков. Это гарантирует, что автоматизированные сеансы следуют более строгим правилам, чем интерактивная разработка.
Генерация аудиторского следа
Хуки PostToolUse в средах CI создают подробные журналы аудита всех операций Claude:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Фоновое логирование не влияет на производительность, но предоставляет полную историю операций для соответствия требованиям и отладки.
Меню /hooks
Claude Code предоставляет команду /hooks, которая отображает все активные хуки для текущего сеанса. Согласно официальной документации, это меню показывает:
- Тип события хука
- Шаблоны сопоставления
- Команда или конечная точка URL
- Является ли хук асинхронным
- Источник конфигурации (проект, пользователь или плагин)
Выбор хука отображает его полную конфигурацию и позволяет временно отключить его для текущего сеанса.
Отключение или удаление хуков
Хуки можно отключить без удаления конфигурации, добавив "enabled": false в определение хука. Это сохраняет конфигурацию, но предотвращает выполнение.
Чтобы окончательно удалить хук, удалите его запись из соответствующего файла settings.json. Изменения вступают в силу при следующем перезапуске сеанса или при выполнении /reload.
Хуки в Skills и Agents
Согласно официальной документации, хуки, определенные в конфигурациях навыков или под-агентов, применяются только при выполнении этого навыка или агента. Это позволяет использовать специализированную автоматизацию для конкретных рабочих процессов.
Под-агент отладки может включать хуки, которые регистрируют все вызовы инструментов:
| { “name”: “debugger”, “hooks”: [ { “event”: “PostToolUse”, “command”: “./scripts/log-debug.sh”, “async”: true } ] } |
Эти хуки срабатывают только во время сеансов агента отладчика, а не во время обычной работы Claude Code.
Ссылка на скрипты по пути
Команды хуков поддерживают как относительные, так и абсолютные пути. Относительные пути разрешаются из корневого каталога проекта, где работает Claude Code.
Рекомендации из обсуждений сообщества:
- Храните скрипты хуков в каталоге .claude/hooks/
- Используйте описательные имена: validate-typescript.sh, а не hook1.sh.
- Сделайте скрипты исполняемыми: chmod +x .claude/hooks/*.sh
- Включите строку shebang: #!/usr/bin/env bash или #!/usr/bin/env python3
- Добавьте обработку ошибок с помощью set -e в bash-скриптах
Будущие возможности хуков
Запросы на добавление функций в GitHub раскрывают запланированные и запрашиваемые улучшения хуков:
- Встроенные скрипты хуков: Определяйте логику хуков непосредственно в settings.json без внешних файлов.
- Интеграция инструментов MCP: Вызывайте инструменты сервера MCP из хуков вместо shell-команд.
- Сотрудничество между несколькими агентами: Хуки, координирующие работу между экземплярами Claude на разных машинах.
- Расширенная типизация: Определение типов TypeScript для схем ввода/вывода хуков.
Согласно проблеме GitHub #4274, запрос на интегрированные типы хуков (инструмент MCP, встроенный скрипт, вызов API) направлен на упрощение конфигурации и улучшение опыта разработчика.
Часто задаваемые вопросы
Могут ли хуки предотвратить выполнение Claude опасных команд?
Да. Хуки PreToolUse могут блокировать любое выполнение инструмента, завершаясь с кодом 1. Это включает в себя редактирование файлов, выполнение команд и вызовы инструментов MCP. Хук получает полный ввод инструмента и может проверять любые критерии перед разрешением операции.
Как отладить хук, который не работает?
Включите отладочное логирование с помощью CLAUDE_DEBUG=1 перед запуском Claude Code. Проверьте журналы сеанса для получения подробной информации о выполнении хуков, включая, какие хуки совпали, отправленный JSON-ввод, вывод stdout/stderr и коды выхода. Тестируйте хуки независимо, передавая образцы JSON в скрипт хука.
Работают ли хуки со всеми платформами Claude Code?
Хуки работают в CLI, настольном приложении и расширении VS Code. Согласно официальной документации, хуки выполняются везде, где Claude Code работает с доступом к файловой системе. Браузерные Claude и мобильные приложения не поддерживают хуки из-за ограничений песочницы.
Могут ли хуки изменять ответы или поведение Claude?
Хуки подсказок впрыскивают инструкции, которые влияют на поведение Claude. Хуки агентов делегируют обработку событий специализированным под-агентам. Однако хуки не могут напрямую изменять сгенерированный текст или процесс рассуждений Claude — они работают, предоставляя контекст и блокируя операции.
В чем разница между асинхронными и синхронными хуками?
Синхронные хуки блокируют рабочий процесс Claude до завершения или тайм-аута. Асинхронные хуки выполняются в фоновом режиме, не блокируя. Синхронные хуки могут предотвратить операции через коды выхода. Асинхронные хуки не могут блокировать, поскольку Claude продолжает работу до завершения хука. Используйте асинхронные для логирования и уведомлений, синхронные для проверки.
Как делиться хуками с командой?
Зафиксируйте файл .claude/settings.json в системе контроля версий. Хуки уровня проекта применяются ко всем членам команды, которые клонируют репозиторий. Для политик всей организации команды могут поддерживать общий файл настроек уровня пользователя, который участники копируют в ~/.claude/settings.json.
Могут ли HTTP-хуки вызывать внутренние API за файрволами?
Да, если Claude Code работает в среде с сетевым доступом к этим API. HTTP-хуки отправляют стандартные POST-запросы с машины, на которой работает Claude Code. Корпоративные файрволы и VPN применяются как обычно. Песочница-прокси, упомянутая в документации, контролирует раскрытие переменных среды, а не маршрутизацию сети.
Увеличивают ли хуки использование токенов Claude Code?
Хуки подсказок впрыскивают текст в контекст Claude, что потребляет токены. Хуки команд и HTTP не влияют напрямую на использование токенов, но их вывод (сообщения об ошибках, предложения) становится частью контекста разговора. Код выхода 2 с пояснительными сообщениями добавляет больше контекста, чем код выхода 1 с простой блокировкой.
Заключение
Хуки Claude Code превращают ИИ-ассистента из мощного инструмента в полностью автоматизированную платформу разработки. Система событий предоставляет точки перехвата на протяжении всего рабочего процесса Claude — от инициализации сеанса до уплотнения контекста.
Хуки команд обрабатывают локальную проверку и форматирование. HTTP-хуки интегрируют внешние службы и базы данных. Хуки подсказок изменяют поведение через впрыск контекста. Вместе они позволяют использовать шаблоны автоматизации, которые применяют политики команды, поддерживают качество кода и интегрируются с существующей инфраструктурой разработки.
Система сопоставления фильтрует хуки для конкретных инструментов и шаблонов файлов. Коды выхода и вывод JSON управляют потоком принятия решений. Асинхронное выполнение предотвращает блокировку медленных операций. Полная схема конфигурации поддерживает все — от простого автоматического форматирования до сложной многоступенчатой проверки.
Начните с простых хуков PostToolUse для форматирования кода. Добавляйте проверку PreToolUse по мере появления политик. Экспериментируйте с хуками подсказок для модификации поведения. Создавайте HTTP-интеграции для общекомандного применения.
Обратитесь к официальной документации Claude Code для полного справочника по хукам и обновленной схемы конфигурации по мере выпуска новых возможностей.
