Қысқаша шолу: Claude Code ілмектері AI кодтау сессияларының белгілі бір тіршілік циклі кезеңдерінде орындалатын автоматтандыру скрипттері болып табылады, бұл әзірлеушілерге реттелетін командаларды орындауға, әрекеттерді валидациялауға, кодды форматтауға, хабарлама жіберуге және жоба ережелерін енгізуге мүмкіндік береді. Бұл ілмектер SessionStart, PreToolUse және PostToolUse сияқты оқиғалар арқылы Claude-тің жұмыс процесіне интеграцияланады, командаға негізделген, HTTP-ге негізделген және іске қосуға негізделген орындау үлгілерін конфигурацияланатын уақытты шектеулермен және шығу коды мінез-құлқымен қолдайды.
Claude Code-тің ілмек жүйесі AI кодтау көмекшісін пайдалы құралдан толық автоматтандырылған әзірлеу ортасына айналдырады. Көптеген әзірлеушілер ілмектер арқылы қол жетімді бақылаудың ауқымын толық түсінбейді.
Мәселе мынада – ілмектер жай ғана файлды өңдегеннен кейін скрипттерді орындауға арналмаған. Олар Claude-тің бүкіл шешім қабылдау процесінде тосқауыл қою нүктелерін қамтамасыз етеді. Команданы орындамас бұрын. Құрал шақыруы сәтсіз болғаннан кейін. Оның рұқсаты қажет болғанда. Тіпті пайдаланушы хабарламаларын өңдемес бұрын.
Бұл нұсқаулық ресми құжаттамадағы барлық нәрсені, сондай-ақ қоғамдастық талқылауларында өндірістік ортада жұмыс істейтін тәжірибелік үлгілерді қамтиды.
Claude Code ілмектері шын мәнінде не істейді
Ресми Claude Code құжаттамасына сәйкес, ілмектер – бұл Claude Code тіршілік циклінің белгілі бір нүктелерінде орындалатын пайдаланушы анықтаған shell командалары, HTTP нүктелері немесе prompt енгізулер. Олар stdin арқылы құрылымдалған JSON кірістерін алады және шығу кодтары немесе HTTP жауаптары арқылы жұмыс процесін бақылайды.
Автоматтандыру көптеген нұсқаулықтар ұсынатынынан әлдеқайда терең. Ілмектер құралды орындауды толығымен блокта алады, Claude-тің ойлауына қосымша контекст енгізе алады, сыртқы қызметтерді іске қоса алады және Claude сыйлауы керек валидация ережелерін енгізе алады.
Үш негізгі ілмек түрі бар:
- Команда ілмектері: stdout, stderr және шығу кодтары арқылы байланысатын Shell скрипттері
- HTTP ілмектері: POST сұрауларын қабылдайтын және JSON жауаптарын қайтаратын қашықтағы нүктелер
- Prompt ілмектері: Белгілі бір оқиғалар кезінде Claude-тің контекстіне енгізілген динамикалық нұсқаулар
Әрбір түр әртүрлі автоматтандыру үлгілеріне қызмет етеді. Команда ілмектері жергілікті валидацияны және форматтауды өңдейді. HTTP ілмектері сыртқы қызметтермен және дерекқорлармен интеграцияланады. Prompt ілмектері сыртқы процестерсіз Claude-тің мінез-құлқын өзгертеді.
Ілмек тіршілік циклі және оқиға жүйесі
Ресми құжаттама Claude Code жұмысы барысында іске қосылатын бірнеше ілмек оқиғаларын (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification және басқалар) анықтайды. Әрқайсысының қашан іске қосылатынын түсіну қандай автоматтандыру мүмкін болатынын анықтайды.
| Оқиға | Қашан орындалады | Блокада жасауға болады |
|---|---|---|
| SessionStart | Сессия бастағанда немесе жалғасқанда | Жоқ |
| UserPromptSubmit | Сіз Claude өңдемес бұрын, хабарлама жібергенде | Иә |
| PreToolUse | Құрал шақырылуы орындалмас бұрын | Иә |
| PermissionRequest | Рұқсат диалогі пайда болғанда | Иә |
| PostToolUse | Құрал шақыруы сәтті аяқталғаннан кейін | Жоқ |
| PostToolUseFailure | Құрал шақыруы сәтсіз болғаннан кейін | Жоқ |
| Notification | Claude Code хабарлама жібергенде | Жоқ |
| SubmitMessage | Claude пайдаланушыға хабарлама жібергенде | Жоқ |
| ContextCompaction | Контекст терезесінің шектері жақындағанда | Жоқ |
Блокада жасау мүмкіндігі ең маңызды. PreToolUse ілмектері қауіпті операцияларды орындамас бұрын блоктауға болады. Шығу коды 1 әрекетті блоктады. Шығу коды 0 оны рұқсат етеді. Шығу коды 2 Claude-ті қайта қарауға шақырады.
Бірақ күтіңіз. PostToolUse ілмектері құрал бұрыннан орындалғандықтан, әрекеттерді қайтара алмайды. Бұл шектеу валидация логикасының қалай құрылатынын анықтайды. Маңызды тексерулер PreToolUse-те болады. Тазалау және форматтау PostToolUse-те болады.
Claude Code орнатқан кезде AI құралдарының артықшылықтарын қараңыз
Егер сіз Claude Code ілмектерімен жұмыс істесеңіз, сіз өзіңіздің жұмыс процесіңіздің айналасында басқа AI құралдарын таңдауыңыз мүмкін. Get AI Perks AI және бұлттық құралдар үшін стартап кредиттерін және бағдарламалық жасақтамалық жеңілдіктерін бір жерде жинайды. Платформада 200-ден астам ұсыныстар бар, әрқайсысы үшін артықшылық шарттары мен талап нұсқаулары бар.
Claude немесе басқа AI құралдарының артықшылықтарын іздеп жүрсіз бе?
Get AI Perks сайтына тексеріңіз:
- Claude және басқа AI құралдарының ұсыныстарын қараңыз
- Өтініш бермес бұрын артықшылық шарттарын салыстырыңыз
- Сіздің құрал стегіңіз бойынша стартап жеңілдіктерін табыңыз
👉 Қазіргі AI бағдарламалық жасақтамасының артықшылықтарын зерттеу үшін Get AI Perks сайтын қараңыз.
Конфигурация және файл құрылымы
Ілмектер жоба ішіндегі .claude/settings.json файлында анықталады. Конфигурация схемасы глобалдық ілмектерді және ілмектер қашан орындалатынын сүзетін құралға арналған сәйкестендіргіштерді қолдайды.
Қарапайым команда ілмегінің құрылымы:
| { “hooks”: [ { “event”: “PostToolUse”, “command”: “prettier –write”, “args”: [“${file}”] } ] } |
${file} айнымалысы құрал кірісінен алынған нақты файл жолына кеңейеді. Ресми құжаттамаға сәйкес, ілмектер команда және 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 өрісі edit_file, execute_command, read_file және create_directory сияқты Claude-тің кірістірілген құралдарымен сәйкестендіріледі.
Қоғамдастық талқылаулары сәйкестендіргіш комбинациялары ЖӘНЕ логикамен жұмыс істейтінін көрсетеді. Ілмек іске қосылуы үшін барлық көрсетілген сәйкестендіргіштер сәйкес келуі керек.
Команда ілмектері: 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(“Қорғалған файлдарды өңдеу мүмкін емес”, file=sys.stderr) sys.exit(1) sys.exit(0) |
Шығу коды 0 операцияға рұқсат етеді. Шығу коды 1 оны блоктады және stderr хабарламасын Claude-ге көрсетеді. Шығу коды 2 арнайы мінез-құлықты оқиғаға байланысты іске қосады.
Шығу коды 2 мінез-құлқы
Ресми ілмектер анықтамасына сәйкес, шығу коды 2-нің оқиғаға арналған арнайы мағынасы бар (PreToolUse: блоктады және қайта қарауды сұрайды; UserPromptSubmit: блоктамай контекст ұсынады; PermissionRequest: рұқсатты блоктады):
- PreToolUse: Құралды блоктады және stderr хабарламасын контекст ретінде пайдаланып, Claude-ті қайта қарауға шақырады
- UserPromptSubmit: stderr шығысын блоктамай қосымша контекст ретінде ұсынады
- PermissionRequest: Рұқсатты беруді блоктады
Бұл қатты блоктау мен рұқсат ету арасындағы ортаңғы жолды жасайды. Claude операция неліктен проблемалы болуы мүмкін екендігі туралы кері байланыс алады және өзінің тәсілін реттей алады.
Асинхронды команда ілмектері
async: true флигі ілмектерді Claude жұмыс процесін блоктамай, фондық режимде орындайды. Бұл орналастыру хабарламалары немесе метрика жинау сияқты баяу операциялар үшін маңызды.
| { “event”: “PostToolUse”, “matcher”: { “toolName”: “execute_command” }, “command”: “./scripts/log-to-analytics.sh”, “async”: true, “timeout”: 30 } |
Async ілмек іске қосылғанда, Claude Code процесті бастайды және дереу жалғастырады. timeout өрісі секундтарда максималды орындау уақытын белгілейді. Егер көрсетілмесе, async ілмектері 10 минуттық әдепкі уақытты шектеуді пайдаланады.
Шынайы сөз: async ілмектері операцияларды блоктамайды, себебі олар Claude жалғастырғаннан кейін орындалады. Олар жазу, хабарламалар және тазалау үшін жұмыс істейді – валидация үшін емес.
HTTP ілмектері: Сыртқы қызмет интеграциясы
HTTP ілмектері JSON пакеттерін қашықтағы нүктелерге POST арқылы жібереді және шешім бақылауы үшін жауаптарды талдайды. Олар валидация қызметтерімен, дерекқорлармен және үшінші тарап құралдарымен интеграциялауға мүмкіндік береді.
Қарапайым 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 ілмектері url, тақырыптар және басқа да мәтіндік өрістерде ${VAR} синтаксисін қолдайды. Айнымалылар Claude Code жұмыс істейтін ортадан кеңейеді.
Ресми MCP құжаттамасына сәйкес, айналалық айнымалыларды кеңейту әдепкі балама синтаксисін қамтиды: ${VAR:-default} VAR орнатылған болса, кеңейеді, әйтпесе әдепкі мәнді пайдаланады.
Қауіпсіздік шектеуі: GitHub мәселесі #28044 бойынша, HTTP ілмектері тек allowedEnvVars конфигурация өрісінде арнайы тізімделген айналалық айнымалыларға қол жеткізе алады. Бұл кездейсоқ құпия деректерді ашудан сақтайды.
Prompt ілмектері: Контекст енгізу
Prompt ілмектері белгілі бір оқиғалар кезінде Claude-тің контекстіне динамикалық нұсқауларды енгізеді. Олар сыртқы процестер мен API шақыруларынсыз мінез-құлықты өзгертеді.
| { “event”: “SessionStart”, “prompt”: “Сіз TypeScript жобасында жұмыс істейсіз. Әрқашан қатаң null тексерулерін қолданыңыз және promises қарағанда async/await-ті қалаңыз.” } |
Енгізілген мәтін сол сессия үшін Claude-тің жүйелік нұсқауларының бөлігі болады. Prompt ілмектері оқиға деректеріне негізделген кеңейетін шаблон айнымалыларын да пайдалана алады.
Динамикалық prompt генерациясы
Ресми құжаттамаға сәйкес, prompt ілмектері динамикалық prompt-тарды генерациялайтын команда өрістерін қолдайды:
| { “event”: “ContextCompaction”, “type”: “prompt”, “command”: “./scripts/generate-context-summary.sh” } |
Команда stdin арқылы стандартты JSON кірісін алады және stdout-қа prompt мәтінін шығарады. Бұл жоба күйіне негізделген контекстке сезімтал нұсқаулықтар генерациялауға мүмкіндік береді.
Агенттік ілмектер
Agent ілмектері тікелей prompt енгізудің орнына оқиғаны өңдейтін қосалқы агентті анықтайды. Қосалқы агент оқиға туралы контекстті алады және көп сатылы ойлауды орындай алады.
| { “event”: “PostToolUseFailure”, “agent”: “debugger”, “agentPrompt”: “Құрал шақыруы сәтсіз болды. Қатені талдап, түзетулерді ұсыныңыз.” } |
Аталған қосалқы агент жоба конфигурациясында анықталуы керек. Agent ілмектері қарапайым prompt енгізу қамтамасыз ете алмайтын күрделі шешім логикасына мүмкіндік береді.
Тәжірибелік ілмек үлгілері
Қоғамдастық талқылаулары және ресми мысалдары өндірісте сенімді жұмыс істейтін нақты автоматтандыру үлгілерін көрсетеді.
Өңдеулерден кейін кодты автоматты форматтау
Ең танымал үлгі 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 операциялары аяқталады. Бұл қолмен staging жасамай, конфигурацияны өзгертулердің аудит іздерін жасайды.
JSON шығысы және шешім бақылауы
Команда ілмектері қарапайым шығу кодтарынан тыс толықтырылған кері байланыс беру үшін құрылымдалған JSON шығара алады. Ресми анықтамаға сәйкес, JSON шығысы Claude шешім қабылдау үшін пайдаланатын көп өрісті жауаптарға мүмкіндік береді.
| { “allowed”: false, “message”: “Бұл файл команда саясатымен қорғалған”, “suggestion”: “src/features/ ішінде жаңа файл жасаңыз” } |
allowed өрісі операцияның жалғасатынын бақылайды. Хабарлама Claude-ке контекст ретінде пайда болады. Ұсыныс өрісі балама тәсілдерді көрсетеді.
Ілмектер JSON шығаруы үшін олар:
- stdout-қа жарамды JSON жазыңыз
- 0 кодымен шығыңыз (рұқсат етілген үшін) немесе 1 (блокталған үшін)
- Ең аз дегенде allowed булеан өрісін қамтыңыз
Claude Code JSON-ды талдайды және оны кері байланыс циклдерін жақсарту үшін пайдаланады. Шығу кодтары әлі де негізгі шешімді анықтайды, бірақ JSON толықтырылған контекст береді.
Ілмек кіріс өрістері сілтемесі
Барлық ілмектер stdin арқылы жалпы өрістермен және оқиғаға арналған деректермен JSON нысанын алады. Толық схеманы түсіну әлдеқайда күрделі ілмек логикасына мүмкіндік береді.
Жалпы кіріс өрістері
Әрбір ілмек осы базалық өрістерді алады:
- event: Ілмек оқиғасының атауы (мысалы, “PreToolUse”)
- sessionId: Ағымдағы Claude сессиясының бірегей идентификаторы
- turnId: Ағымдағы әңгіме айналымының идентификаторы
- timestamp: Оқиға іске қосылған уақыттың ISO 8601 штампы
Құрал оқиға өрістері
PreToolUse, PostToolUse және PostToolUseFailure оқиғалары қамтиды:
- toolName: Шақырылып жатқан құралдың атауы (edit_file, execute_command және т.б.)
- toolInput: Құралдың кіріс параметрлерін қамтитын нысан
- toolResponse: Құралдың шығыс деректері (тек PostToolUse үшін)
- error: Қате туралы мәліметтер, хабарламаны және кодын қамтиды (тек PostToolUseFailure үшін)
toolInput құрылымы құралға байланысты өзгереді. edit_file үшін ол жолды және мазмұнды қамтиды. execute_command үшін ол команданы және аргументтерді қамтиды.
Рұқсат оқиға өрістері
PermissionRequest оқиғалары қамтиды:
- permissionType: Сұралған рұқсаттың түрі (file_write, command_execute және т.б.)
- requestedAction: Рұқсатты талап ететін нақты әрекет
- resourcePath: Файл жолы немесе әсер ететін ресурс идентификаторы
MCP құрал ілмектері
Ресми ілмектер анықтамасына сәйкес, ілмектер mcpTool сәйкестендіргіш өрісін пайдаланып, Модель Контексті Протоколы (MCP) құралдарына сәйкес келе алады. Бұл Claude MCP серверлерінен алынған сыртқы құралдарды пайдаланған кезде ілмекті орындауға мүмкіндік береді.
| { “event”: “PreToolUse”, “matcher”: { “mcpTool”: “database/query” }, “command”: “./scripts/validate-sql.sh” } |
mcpTool мәні формат сервер-аты/құрал-аты бойынша құрал атауымен сәйкес келеді. Бұл дерекқор сұраулары, API шақырулары немесе басқа сыртқы операциялар үшін валидация логикасына мүмкіндік береді.
GitHubFeature іздеулері MCP сервер хабарламаларын қарауға және сыртқы оқиғаларға жауап беруге болатын ілмектерді қамтитын тереңірек MCP интеграциясына қызығушылықтың өсіп келе жатқанын көрсетеді.
Қауіпсіздік ескертулері
Ілмектер Claude Code-пен бірдей рұқсаттармен орындалады. Бұл көп пайдаланушылы орталар мен ортақ конфигурациялар үшін қауіпсіздік салдарларын тудырады.
Команда орындау Sandbox
GitHub мәселесі #28044 бойынша, HTTP ілмектері желілік қол жетімділікті шектейтін және айналалық айнымалыларды сүзетін sandbox прокси арқылы өтеді. Команда ілмектерінде мұндай шектеулер жоқ – олар толық shell қол жетімділігімен жұмыс істейді.
Құжаттама келесі практикаларды ұсынады:
- Ешқашан ілмек командаларына құпия деректерді сақтамаңыз
- Сезімтал деректер үшін айналалық айнымалыларды пайдаланыңыз
- ${...} кеңеюлерінен алынған барлық кірістерді валидациялаңыз
- Сыртқы қызметтер үшін уақытты шектеулер енгізіңіз
- Сәтсіздіктер кезінде блоктарды болдырмау үшін асинхронды ілмектерді пайдаланыңыз
Ілмек орындауды оқшаулау
~/.claude/settings.json файлындағы пайдаланушы деңгейіндегі ілмектер барлық жобаларға қолданылады. Бұл әртүрлі сенім шекараларында жұмыс істегенде тәуекелдерді тудырады. Жоба деңгейіндегі ілмектер пайдаланушы ілмектерін басып озады, бірақ оларды толығымен өшіре алмайды.
Claude Code-тегі /hooks мәзірі ағымдағы сессия үшін барлық белсенді ілмектерді көрсетеді. Сезімтал жобалармен жұмыс істемес бұрын бұл тізімді қарау әлеуетті қауіпсіздік мәселелерін анықтауға көмектеседі.
Жөндеу және ақауларды түзету
Ілмек сәтсіздіктері әрдайым Claude әңгімесінде анық көрінбейді. Ресми құжаттама бірнеше жөндеу тәсілдерін ұсынады.
Ілмек орындау журналдары
Claude Code ілмек орындауын сессияның жөндеу шығысында жазады. Ақауларды түзету нұсқаулығына сәйкес, жөндеу жазуын қосусуды анықтайды:
- Әр оқиға үшін қандай ілмектер сәйкес келді
- Әр ілмекке жіберілген JSON кірісі
- Ілмек процестерінің stdout және stderr шығысы
- Шығу кодтары және орындау уақыты
- HTTP ілмектері үшін HTTP жауап кодтары мен денелері
Claude Code-ті бастамас бұрын ортада CLAUDE_DEBUG=1 орнату арқылы жөндеу жазуын қосыңыз.
Ілмектерді жеке тестілеу
Команда ілмектерін қолмен JSON кірісін құру арқылы Claude Code-тен тыс тестілеуге болады:
| 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 флигі ілмек скрипттерінде шартты валидация логикасын іске қосады. Бұл автоматтандырылған сессиялардың интерактивті әзірлеуден гөрі қатаң ережелерді сақтауын қамтамасыз етеді.
Аудит жазуын генерациялау
CI орталарындағы PostToolUse ілмектері барлық Claude операцияларының толық аудит журналдарын жасайды:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
Фондық жазу өнімділікке әсер етпейді, бірақ сәйкестік пен жөндеу үшін толық операция тарихын қамтамасыз етеді.
/hooks Мәзірі
Claude Code /hooks командасын ұсынады, ол ағымдағы сессия үшін барлық белсенді ілмектерді көрсетеді. Ресми құжаттамаға сәйкес, бұл мәзір көрсетеді:
- Ілмек оқиғасының түрі
- Сәйкестендіргіш үлгілері
- Команда немесе URL нүктесі
- Ілмектің async істейтіндігі
- Конфигурация көзі (жоба, пайдаланушы немесе плугин)
Ілмекті таңдау оның толық конфигурациясын көрсетеді және ағымдағы сессия үшін уақытша өшіруге мүмкіндік береді.
Ілмектерді өшіру немесе жою
Ілмектерді конфигурацияны жоймай өшіруге болады, бұл ілмек анықтамасына "enabled": false қосу арқылы. Бұл конфигурацияны сақтай отырып, орындауды болдырмайды.
Ілмекті тұрақты жою үшін, оның жазбасын тиісті settings.json файлынан жойыңыз. Өзгерістер келесі сессияны қайта іске қосқанда немесе /reload орындағанда күшіне енеді.
Ілмектер дағдылар мен агенттерде
Ресми құжаттамаға сәйкес, дағды немесе қосалқы агент конфигурациялары ішінде анықталған ілмектер тек сол дағды немесе агент орындалған кезде қолданылады. Бұл арнайы жұмыс процестері үшін арнайы автоматтандыруға мүмкіндік береді.
Жөндеу қосалқы агенті барлық құрал шақыруларын жазатын ілмектерді қамтуы мүмкін:
| { “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
- Шебанг жолын қосыңыз: #!/usr/bin/env bash немесе #!/usr/bin/env python3
- Bash скрипттерінде set -e бар қате өңдеуін қосыңыз
Болашақ ілмек мүмкіндіктері
GitHubFeature іздеулері жоспарланған және сұралған ілмек жақсартуларын көрсетеді:
- Кірістірілген скрипт ілмектері: сыртқы файлдарсыз settings.json ішінде ілмек логикасын тікелей анықтау
- MCP құрал интеграциясы: қабырға командаларының орнына ілмектерден MCP сервер құралдарын шақыру
- Көп агентті ынтымақтастық: әртүрлі машиналардағы Claude инстанстаралы арасындағы үйлестіретін ілмектер
- Жақсартылған теру: ілмек кіріс/шығыс схемалары үшін TypeScript тип анықтамалары
GitHub мәселесі #4274 бойынша, біріктірілген ілмек түрлеріне (MCP құрал, кірістірілген скрипт, API шақыру) сұрау конфигурацияны жеңілдетуге және әзірлеуші тәжірибесін жақсартуға бағытталған.
Жиі қойылатын сұрақтар
Ілмектер Claude-ті қауіпті командаларды орындаудан тоқтата ала ма?
Иә. PreToolUse ілмектері 1 кодымен шығу арқылы кез келген құралды орындауды блоктай алады. Бұл файлды өңдеуді, команданы орындауды және MCP құрал шақыруларын қамтиды. Ілмек толық құрал кірісін алады және операцияға рұқсат бермес бұрын кез келген критерийлерге қарсы валидациялай алады.
Жұмыс істемейтін ілмекті қалай жөндеуге болады?
Claude Code-ті бастамас бұрын CLAUDE_DEBUG=1 пайдаланып жөндеу журналын қосыңыз. Ілмек орындау егжей-тегжейлері, қандай ілмектер сәйкес келді, жіберілген JSON кірісі, stdout/stderr шығысы және шығу кодтары үшін сессия журналдарын тексеріңіз. Үлгі JSON-ды ілмек скриптіне жіберу арқылы ілмектерді жеке тестілеңіз.
Ілмектер барлық Claude Code платформаларымен жұмыс істей ме?
Ілмектер CLI, жұмыс үстелі қолданбасы және VS Code кеңейтімінде жұмыс істейді. Ресми құжаттамаға сәйкес, ілмектер Claude Code файл жүйесіне қол жетімділігі бар жерде жұмыс істейді. Браузерге негізделген Claude және мобильді қосымшалар sandbox шектеулеріне байланысты ілмектерді қолдамайды.
Ілмектер Claude Code жауаптарын немесе мінез-құлқын өзгерте ала ма?
Prompt ілмектері Claude-тің мінез-құлқына әсер ететін нұсқауларды енгізеді. Agent ілмектері арнайы қосалқы агенттерге оқиғаны өңдеуді тапсырады. Дегенмен, ілмектер Claude-тің генерацияланған мәтінін немесе ойлау процесін тікелей өзгерте алмайды – олар контекст беру және операцияларды блоктау арқылы жұмыс істейді.
Async және sync ілмектерінің айырмашылығы неде?
Синхронды ілмектер аяқталғанша немесе уақыт шектеуі аяқталғанша Claude жұмыс процесін блоктады. Асинхронды ілмектер фондық режимде, блоктамай жұмыс істейді. Sync ілмектері шығу кодтары арқылы операцияларды блоктай алады. Async ілмектері блоктай алмайды, себебі Claude ілмек аяқталғанға дейін жалғасады. Жазу және хабарламалар үшін async, валидация үшін sync пайдаланыңыз.
Ілмектерді команда бойынша қалай бөлісуге болады?
.claude/settings.json файлына нұсқауды нұсқауларға қосыңыз. Жоба деңгейіндегі ілмектер репозиторийді клондейтін барлық команда мүшелеріне қолданылады. Ұйым бойынша саясаттар үшін командалар команда мүшелері ~/.claude/settings.json файлына көшіретін ортақ пайдаланушы деңгейіндегі параметрлер файлын сақтай алады.
HTTP ілмектері брандмауэрлер артындағы ішкі API-лерді шақыра ала ма?
Иә, егер Claude Code сол API-лерге желілік қол жетімділігі бар ортада жұмыс істесе. HTTP ілмектері Claude Code жұмыс істейтін машинадан стандартты POST сұрауларын жасайды. Корпоративті брандмауэрлер және VPN әдеттегідей қолданылады. Құжаттамада айтылған sandbox проксисі желілік маршруттау емес, айналалық айнымалыларды ашуды бақылайды.
Ілмектер Claude Code токенін пайдалануды арттыра ма?
Prompt ілмектері Claude-тің контекстіне мәтінді енгізеді, бұл токендерді тұтынады. Команда және HTTP ілмектері токен қолданысына тікелей әсер етпейді, бірақ олардың шығысы (қате хабарламалары, ұсыныстар) әңгіме контекстінің бөлігі болады. Шығу коды 2 түсіндірме хабарламаларымен қарапайым блоктау 1 кодымен қарағанда көбірек контекст қосады.
Қорытынды
Claude Code ілмектері AI көмекшісін қуатты құралдан толық автоматтандырылған әзірлеу платформасына айналдырады. Оқиға жүйесі Claude жұмыс процесінде – сессия инициализациясынан бастап контексті компактизациялауға дейін – тосқауыл қою нүктелерін қамтамасыз етеді.
Команда ілмектері жергілікті валидация мен форматтауды өңдейді. HTTP ілмектері сыртқы қызметтер мен дерекқорларды интеграциялайды. Prompt ілмектері контекст енгізу арқылы мінез-құлықты өзгертеді. Бірге, олар команда саясаттарын енгізетін, код сапасын сақтайтын және қолданыстағы әзірлеу инфрақұрылымымен интеграцияланатын автоматтандыру үлгілерін мүмкін етеді.
Сәйкестендіргіш жүйесі ілмектерді белгілі бір құралдар мен файл үлгілеріне сүзгілейді. Шығу кодтары және JSON шығысы шешім ағынын бақылайды. Async орындау баяу операцияларда блоктарды болдырмайды. Толық конфигурация схемасы қарапайым автоматты форматтаудан бастап күрделі көп сатылы валидацияға дейінгі барлық нәрсені қолдайды.
Кодты форматтау үшін қарапайым PostToolUse ілмектерімен бастаңыз. Саясаттар пайда болған кезде PreToolUse валидациясын қосыңыз. Мінез-құлықты өзгерту үшін prompt ілмектерін эксперимент етіңіз. Команда бойынша енгізу үшін HTTP интеграцияларын жасаңыз.
Жаңа мүмкіндіктер шыққан кезде толық ілмектер сілтемесі және жаңартылған конфигурация схемасы үшін ресми Claude Code құжаттамасын тексеріңіз.
