خلاصه سریع: هوکهای Claude Code اسکریپتهای اتوماسیونی هستند که در نقاط خاصی از چرخه حیات جلسات کدنویسی هوش مصنوعی اجرا میشوند و به توسعهدهندگان اجازه میدهند دستورات سفارشی را اجرا کنند، اقدامات را تأیید کنند، کد را قالببندی کنند، اعلانها را ارسال کنند و قوانین پروژه را اجرا کنند. این هوکها از طریق رویدادهایی مانند SessionStart، PreToolUse و PostToolUse با گردش کار Claude ادغام میشوند و از الگوهای اجرای مبتنی بر دستور، مبتنی بر HTTP و مبتنی بر پرامپت با مهلتهای زمانی قابل تنظیم و رفتار کد خروج پشتیبانی میکنند.
سیستم هوک Claude Code، دستیار کدنویسی هوش مصنوعی را از یک ابزار مفید به یک محیط توسعه کاملاً خودکار تبدیل میکند. بیشتر توسعهدهندگان از میزان کنترلی که از طریق هوکها در دسترس است، آگاه نیستند.
نکته اینجاست که هوکها فقط برای اجرای اسکریپتها پس از ویرایش فایل نیستند. آنها نقاط رهگیری را در کل فرآیند تصمیمگیری Claude فراهم میکنند. قبل از اجرای یک دستور. پس از شکست فراخوانی ابزار. زمانی که نیاز به مجوز دارد. حتی قبل از پردازش پرامپتهای کاربر.
این راهنما همه چیزهایی را که مستندات رسمی ارائه میدهند، به علاوه الگوهای عملی را پوشش میدهد که بحثهای جامعه نشان میدهند در محیطهای تولیدی واقعاً کار میکنند.
هوکهای Claude Code واقعاً چه کاری انجام میدهند
بر اساس مستندات رسمی Claude Code، هوکها دستورات شل، نقاط پایانی HTTP یا تزریق پرامپت تعریف شده توسط کاربر هستند که در نقاط خاصی از چرخه حیات Claude Code اجرا میشوند. آنها ورودی JSON ساختاریافته را از طریق stdin دریافت میکنند و گردش کار را از طریق کدهای خروج یا پاسخهای HTTP کنترل میکنند.
اتوماسیون عمیقتر از آنچه اکثر راهنماها نشان میدهند، عمل میکند. هوکها میتوانند اجرای ابزار را کاملاً مسدود کنند، زمینه اضافی را به استدلال Claude تزریق کنند، سرویسهای خارجی را راهاندازی کنند و قوانین اعتبارسنجی را که Claude باید رعایت کند، اجرا کنند.
سه نوع اصلی هوک وجود دارد:
- هوکهای دستور: اسکریپتهای شل که از طریق 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 قرار گیرند.
مرور تخفیفهای ابزار هوش مصنوعی هنگام راهاندازی 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 مطابقت دارد.
بحثهای جامعه نشان میدهند که ترکیبات منطبق کننده با منطق AND کار میکنند. برای اینکه هوک اجرا شود، همه منطبق کنندههای مشخص شده باید مطابقت داشته باشند.
هوکهای دستور: ادغام اسکریپت شل
هوکهای دستور، دستورات یا اسکریپتهای شل را با ورودی JSON ساختاریافته اجرا میکنند. آنها رایجترین نوع هوک برای اتوماسیون محلی را نشان میدهند.
مستندات رسمی مشخص میکند که هوکهای دستور JSON را از طریق stdin با این ساختار دریافت میکنند:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }اسکریپتها این ورودی را تجزیه میکنند تا تصمیمگیری کنند. یک هوک اعتبارسنجی پایتون ممکن است به این صورت باشد:#!/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 payloadهای JSON را به نقاط پایانی از راه دور ارسال میکنند و پاسخها را برای کنترل تصمیمگیری تجزیه میکنند. آنها امکان ادغام با سرویسهای اعتبارسنجی، پایگاههای داده و ابزارهای شخص ثالث را فراهم میکنند.
پیکربندی پایه هوک HTTP:
| { “event”: “PreToolUse”, “url”: “api.example.com/validate”, “headers”: { “Authorization”: “Bearer ${API_TOKEN}” }, “timeout”: 5 } |
ساختار payload با ورودی هوک دستور مطابقت دارد اما به عنوان بدنه POST HTTP میرسد. پاسخ، اقدام بعدی Claude را تعیین میکند.
مدیریت پاسخ HTTP
بر اساس مستندات رسمی، هوکهای HTTP پاسخها را بر اساس کد وضعیت و محتوای بدنه تفسیر میکنند:
| کد وضعیت | اثر | منبع پیام |
|---|---|---|
| 200 | اجازه عملیات | بدنه پاسخ (اختیاری) |
| 400 | مسدود کردن عملیات | بدنه پاسخ نشان داده شده به Claude |
| 500 | خطای هوک، اجازه عملیات | ثبت شده اما به Claude نشان داده نمیشود |
| دیگر | اجازه عملیات | شکست هوک مانع گردش کار نمیشود |
بدنه پاسخ میتواند شامل یک فیلد پیام باشد که Claude آن را به عنوان زمینه میبیند. این به سرویسهای اعتبارسنجی اجازه میدهد تا دلیل مسدود شدن یک عملیات را توضیح دهند.
درونیابی متغیر محیطی
هوکهای HTTP از سینتکس ${VAR} در url، headers و سایر فیلدهای رشته پشتیبانی میکنند. متغیرها از محیطی که Claude Code در آن اجرا میشود، گسترش مییابند.
بر اساس مستندات رسمی MCP، بسط متغیر محیطی شامل یک سینتکس پیشفرض جایگزین است: ${VAR:-default} اگر VAR تنظیم شده باشد، آن را گسترش میدهد، در غیر این صورت از مقدار پیشفرض استفاده میکند.
محدودیت امنیتی: طبق شماره 28044 مسئله GitHub، هوکهای HTTP فقط میتوانند به متغیرهای محیطی که به صراحت در فیلد پیکربندی allowedEnvVars لیست شدهاند، دسترسی داشته باشند. این از افشای تصادفی اعتبار جلوگیری میکند.
هوکهای پرامپت: تزریق زمینه
هوکهای پرامپت، دستورالعملهای پویا را در زمینه Claude در رویدادهای خاص تزریق میکنند. آنها رفتار را بدون فرآیندهای خارجی یا فراخوانی API تغییر میدهند.
| { “event”: “SessionStart”, “prompt”: “شما روی یک پروژه TypeScript کار میکنید. همیشه از بررسیهای null سختگیرانه استفاده کنید و await ناهمزمان را به promiseها ترجیح دهید.” } |
متن تزریق شده بخشی از دستورالعملهای سیستمی 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 اجرا میشوند. این پیامدهای امنیتی برای محیطهای چند کاربره و پیکربندیهای مشترک ایجاد میکند.
Sandbox اجرای دستور
طبق شماره 28044 مسئله GitHub، هوکهای HTTP از طریق یک پروکسی sandbox هدایت میشوند که دسترسی شبکه را محدود کرده و متغیرهای محیطی را فیلتر میکند. هوکهای دستور چنین محدودیتهایی ندارند - آنها با دسترسی کامل شل اجرا میشوند.
مستندات این شیوهها را توصیه میکند:
- هرگز اعتبارنامهها را در دستورات هوک ذخیره نکنید
- از متغیرهای محیطی برای دادههای حساس استفاده کنید
- همه ورودیهای گسترشهای ${...} را اعتبارسنجی کنید
- محدودیتهای مهلت زمانی برای سرویسهای خارجی پیادهسازی کنید
- از هوکهای ناهمزمان برای عملیات غیرضروری برای جلوگیری از مسدود شدن در صورت شکست استفاده کنید
جداسازی اجرای هوک
هوکهای سطح کاربر در ~/.claude/settings.json به همه پروژهها اعمال میشوند. این در هنگام کار در مرزهای مختلف اعتماد، خطراتی را ایجاد میکند. هوکهای سطح پروژه، هوکهای کاربر را لغو میکنند اما نمیتوانند آنها را کاملاً غیرفعال کنند.
منوی /hooks در Claude Code تمام هوکهای فعال را برای جلسه فعلی نمایش میدهد. بررسی این لیست قبل از کار بر روی پروژههای حساس به شناسایی نگرانیهای امنیتی احتمالی کمک میکند.
اشکالزدایی و عیبیابی
شکستهای هوک همیشه به وضوح در مکالمه Claude ظاهر نمیشوند. مستندات رسمی چندین رویکرد اشکالزدایی را ارائه میدهد.
لاگهای اجرای هوک
Claude Code اجرای هوک را به خروجی اشکالزدایی جلسه گزارش میکند. طبق راهنمای عیبیابی، فعال کردن گزارشگیری اشکالزدایی موارد زیر را آشکار میکند:
- کدام هوکها برای هر رویداد مطابقت داشتند
- ورودی JSON ارسال شده به هر هوک
- خروجی stdout و stderr از فرآیندهای هوک
- کدهای خروج و زمان اجرا
- کدهای وضعیت و بدنه پاسخ HTTP برای هوکهای HTTP
با تنظیم CLAUDE_DEBUG=1 در محیط قبل از شروع Claude Code، گزارشگیری اشکالزدایی را فعال کنید.
تست مستقل هوکها
هوکهای دستور را میتوان با ساخت دستی ورودی 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 منطق اعتبارسنجی شرطی را در اسکریپتهای هوک فعال میکند. این اطمینان حاصل میکند که جلسات خودکار از قوانین سختگیرانهتری نسبت به توسعه تعاملی پیروی میکنند.
تولید مسیر حسابرسی
هوکهای PostToolUse در محیطهای CI گزارشهای حسابرسی دقیقی از تمام عملیات Claude ایجاد میکنند:
| { “event”: “PostToolUse”, “command”: “./scripts/log-to-database.sh”, “async”: true } |
گزارشگیری پسزمینه بر عملکرد تأثیر نمیگذارد اما تاریخچه کامل عملیات را برای انطباق و اشکالزدایی فراهم میکند.
منوی /hooks
Claude Code یک دستور /hooks ارائه میدهد که تمام هوکهای فعال را برای جلسه فعلی نمایش میدهد. طبق مستندات رسمی، این منو موارد زیر را نشان میدهد:
- نوع رویداد هوک
- الگوهای منطبق کننده
- دستور یا نقطه پایانی URL
- اینکه آیا هوک به صورت ناهمزمان اجرا میشود
- منبع پیکربندی (پروژه، کاربر یا افزونه)
انتخاب یک هوک، پیکربندی کامل آن را نشان داده و امکان غیرفعال کردن موقت آن را برای جلسه فعلی فراهم میکند.
غیرفعال کردن یا حذف هوکها
هوکها را میتوان بدون حذف پیکربندی با افزودن "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
- خط shebang را شامل کنید: #!/usr/bin/env bash یا #!/usr/bin/env python3
- با set -e در اسکریپتهای bash مدیریت خطا را اضافه کنید
قابلیتهای آینده هوک
درخواستهای ویژگی GitHub، بهبودهای برنامهریزی شده و درخواستی هوک را نشان میدهند:
- هوکهای اسکریپت درون خطی: منطق هوک را مستقیماً در settings.json بدون فایلهای خارجی تعریف کنید
- ادغام ابزار MCP: ابزارهای سرور MCP را از هوکها به جای دستورات شل فراخوانی کنید
- همکاری چند عاملی: هوکهایی که بین نمونههای Claude در ماشینهای مختلف هماهنگ میکنند
- تایپهای پیشرفته: تعاریف نوع TypeScript برای طرحهای ورودی/خروجی هوک
طبق شماره 4274 مسئله GitHub، درخواست انواع هوک یکپارچه (ابزار 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 را تغییر دهند؟
هوکهای پرامپت، دستورالعملهایی را تزریق میکنند که بر رفتار Claude تأثیر میگذارد. هوکهای عامل، مدیریت رویداد را به عوامل فرعی تخصصی واگذار میکنند. با این حال، هوکها نمیتوانند مستقیماً متن تولید شده یا فرآیند استدلال Claude را تغییر دهند - آنها با ارائه زمینه و مسدود کردن عملیات کار میکنند.
تفاوت بین هوکهای ناهمزمان و همزمان چیست؟
هوکهای همزمان، گردش کار Claude را تا اتمام یا مهلت زمانی مسدود میکنند. هوکهای ناهمزمان در پسزمینه و بدون مسدود کردن اجرا میشوند. هوکهای همزمان میتوانند از طریق کدهای خروج از عملیات جلوگیری کنند. هوکهای ناهمزمان نمیتوانند مسدود کنند زیرا Claude قبل از اتمام هوک ادامه مییابد. از ناهمزمان برای گزارشگیری و اعلانها، و همزمان برای اعتبارسنجی استفاده کنید.
چگونه هوکها را در بین یک تیم به اشتراک بگذارم؟
فایل .claude/settings.json را به کنترل نسخه متعهد کنید. هوکهای سطح پروژه به همه اعضای تیم که مخزن را کلون میکنند، اعمال میشود. برای سیاستهای در سطح سازمان، تیمها میتوانند یک فایل تنظیمات مشترک در سطح کاربر نگهداری کنند که اعضا آن را در ~/.claude/settings.json کپی کنند.
آیا هوکهای HTTP میتوانند APIهای داخلی پشت فایروالها را فراخوانی کنند؟
بله، اگر Claude Code در محیطی با دسترسی شبکه به آن APIها اجرا شود. هوکهای HTTP درخواستهای POST استاندارد را از ماشینی که Claude Code را اجرا میکند، ارسال میکنند. فایروالها و VPNهای شرکتی به طور معمول اعمال میشوند. پروکسی sandbox ذکر شده در مستندات، قرار گرفتن در معرض متغیرهای محیطی را کنترل میکند، نه مسیریابی شبکه.
آیا هوکها مصرف توکن Claude Code را افزایش میدهند؟
هوکهای پرامپت، متن را به زمینه Claude تزریق میکنند که توکن مصرف میکند. هوکهای دستور و HTTP مستقیماً بر مصرف توکن تأثیر نمیگذارند، اما خروجی آنها (پیامهای خطا، پیشنهادات) بخشی از زمینه مکالمه میشود. کد خروج 2 با پیامهای توضیحی، زمینه بیشتری نسبت به کد خروج 1 با مسدود کردن ساده اضافه میکند.
نتیجهگیری
هوکهای Claude Code، دستیار هوش مصنوعی را از یک ابزار قدرتمند به یک پلتفرم توسعه کاملاً خودکار تبدیل میکنند. سیستم رویداد، نقاط رهگیری را در سراسر گردش کار Claude - از مقداردهی اولیه جلسه تا فشردهسازی زمینه - فراهم میکند.
هوکهای دستور، اعتبارسنجی و قالببندی محلی را مدیریت میکنند. هوکهای HTTP، سرویسها و پایگاههای داده خارجی را ادغام میکنند. هوکهای پرامپت، رفتار را از طریق تزریق زمینه تغییر میدهند. در مجموع، اینها الگوهای اتوماسیون را امکانپذیر میسازند که سیاستهای تیم را اجرا میکنند، کیفیت کد را حفظ میکنند و با زیرساخت توسعه موجود ادغام میشوند.
سیستم منطبق کننده، هوکها را برای ابزارها و الگوهای فایل خاص فیلتر میکند. کدهای خروج و خروجی JSON جریان تصمیمگیری را کنترل میکنند. اجرای ناهمزمان از مسدود شدن عملیات کند جلوگیری میکند. طرح پیکربندی کامل، همه چیز را از قالببندی خودکار ساده تا اعتبارسنجی پیچیده چند مرحلهای پشتیبانی میکند.
با هوکهای ساده PostToolUse برای قالببندی کد شروع کنید. با ظهور سیاستها، اعتبارسنجی PreToolUse را اضافه کنید. با هوکهای پرامپت برای اصلاح رفتار آزمایش کنید. ادغامهای HTTP را برای اجرای در سطح تیم بسازید.
برای مرجع کامل هوکها و طرح پیکربندی بهروز شده، مستندات رسمی Claude Code را بررسی کنید، زیرا قابلیتهای جدید منتشر میشوند.
