ملخص سريع: خطافات 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.
تصفح مزايا أدوات الذكاء الاصطناعي أثناء إعداد 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} إلى مسار الملف الفعلي من مدخلات الأداة. وفقًا للوثائق الرسمية، تدعم الخطافات هذه التوسعات المتغيرة في حقول الأوامر و 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 بناء عالمي. يطابق حقل toolName الأدوات المضمنة في Claude مثل edit_file، وexecute_command، وread_file، وcreate_directory.
تكشف مناقشات المجتمع أن مجموعات المطابقة تعمل بمنطق AND. يجب أن تتطابق جميع المطابقات المحددة حتى يتم تشغيل الخطاف.
خطافات الأوامر: التكامل مع نصوص Shell
تقوم خطافات الأوامر بتنفيذ أوامر shell أو نصوص برمجية مع مدخلات JSON مهيكلة. إنها تمثل النوع الأكثر شيوعًا من الخطافات للأتمتة المحلية.
تحدد الوثائق الرسمية أن خطافات الأوامر تتلقى JSON عبر stdin بهذا الهيكل:
| { “event”: “PreToolUse”, “toolName”: “edit_file”, “toolInput”: { “path”: “src/app.ts”, “content”: “…” }, “sessionId”: “abc123”, “turnId”: “turn-456” }Scripts parse this input to make decisions. A Python validation hook might look like:#!/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 العملية ويستمر على الفور. يحدد حقل المهلة الحد الأقصى لوقت التنفيذ بالثواني. إذا لم يتم تحديده، تستخدم الخطافات غير المتزامنة مهلة افتراضية مدتها 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 ورؤوس الحقول الأخرى النصية. تتوسع المتغيرات من البيئة التي يعمل فيها Claude Code.
وفقًا للوثائق الرسمية لـ MCP، يتضمن توسيع متغير البيئة صيغة احتياطية افتراضية: ${VAR:-default} يتوسع إلى VAR إذا تم تعيينه، وإلا فإنه يستخدم القيمة الافتراضية.
قيد الأمان: وفقًا لمشكلة GitHub #28044، يمكن لخطافات HTTP الوصول فقط إلى متغيرات البيئة المدرجة صراحةً في حقل التكوين allowedEnvVars. هذا يمنع التعرض غير المقصود للاعتمادات.
خطافات المطالبات: حقن السياق
تقوم خطافات المطالبات بحقن تعليمات ديناميكية في سياق Claude في أحداث محددة. إنها تعدل السلوك دون عمليات خارجية أو استدعاءات API.
| { “event”: “SessionStart”, “prompt”: “أنت تعمل على مشروع TypeScript. استخدم دائمًا فحوصات صارمة للقيمة الفارغة وفضل async/await على الوعود.” } |
يصبح النص المحقون جزءًا من تعليمات النظام لـ 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 إلى مدخلات
وفقًا لدليل سير العمل الرسمي، يمكن لخطافات الإشعارات تشغيل تنبيهات سطح المكتب أو إرسال رسائل إلى خدمات خارجية:
| { “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 (للمنع)
- تضمين حقل boolean المسموح به على الأقل
يقوم 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، فإنه يحتوي على المسار والمحتوى. بالنسبة لـ execute_command، فإنه يحتوي على الأمر و arguments.
حقول حدث الإذن
تتضمن أحداث 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 عبر وكيل صندوق رمل يقيد الوصول إلى الشبكة ويقوم بتصفية متغيرات البيئة. لا تتمتع خطافات الأوامر بهذه القيود - فهي تعمل مع وصول shell كامل.
توصي الوثائق بهذه الممارسات:
- لا تخزن الاعتمادات أبدًا في أوامر الخطاف
- استخدم متغيرات البيئة للبيانات الحساسة
- التحقق من صحة جميع المدخلات من توسعات ${...}
- تطبيق حدود المهلة للخدمات الخارجية
- استخدم الخطافات غير المتزامنة للعمليات غير الحرجة لمنع الحظر عند حدوث فشل
عزل تنفيذ الخطاف
تنطبق الخطافات على مستوى المستخدم في ~/.claude/settings.json على جميع المشاريع. هذا يخلق مخاطر عند العمل عبر حدود الثقة المختلفة. تتجاوز خطافات مستوى المشروع خطافات المستخدم ولكن لا يمكنها تعطيلها بالكامل.
يعرض قائمة /hooks في Claude Code جميع الخطافات النشطة للجلسة الحالية. يساعد مراجعة هذه القائمة قبل العمل على مشاريع حساسة في تحديد مخاوف الأمان المحتملة.
التصحيح واستكشاف الأخطاء وإصلاحها
لا تظهر حالات فشل الخطاف دائمًا بوضوح في محادثة Claude. توفر الوثائق الرسمية عدة طرق لتصحيح الأخطاء.
سجلات تنفيذ الخطاف
يقوم Claude Code بتسجيل تنفيذ الخطاف في مخرجات تصحيح الجلسة. وفقًا لدليل استكشاف الأخطاء وإصلاحها، يكشف تمكين تسجيل التصحيح عن:
- الخطافات التي طابقت لكل حدث
- مدخلات JSON المرسلة إلى كل خطاف
- مخرجات stdout و stderr من عمليات الخطاف
- رموز الخروج ووقت التنفيذ
- رموز الاستجابة وجسم الاستجابة لخطافات 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 دقائق قصيرة جدًا للعمليات البطيئة - زدها باستخدام حقل المهلة
- فشل توسيع المسار: متغيرات مثل ${file} غير معرفة للأحداث التي لا تتضمن سياق ملف
- أخطاء الأذونات: تفتقر نصوص الخطاف البرمجية إلى أذونات التنفيذ - قم بتشغيل chmod +x script.sh
- أخطاء تحليل JSON: مخرجات JSON مشوهة من الخطافات - تحقق باستخدام jq قبل الإرجاع
- عدم توفر متغير البيئة: المتغيرات غير ممررة إلى عملية الخطاف - تحقق من بيئة Claude Code
آثار أداء الخطاف
تحظر الخطافات المتزامنة سير عمل Claude حتى الاكتمال. تمنع المهلة الافتراضية البالغة 10 دقائق التعليق غير المحدد، ولكن حتى التأخيرات القصيرة تتراكم عبر عمليات متعددة.
يبلغ الممارسون عن أن خطافات التحقق البسيطة لها تأثير أداء ضئيل. تسبب خطافات تنسيق الملفات تأثيرًا ملحوظًا ولكنه مقبول على الأداء. يمكن لاستدعاءات API الخارجية أن تخلق احتكاكًا في سير العمل. تستفيد عمليات الحوسبة الثقيلة من التنفيذ غير المتزامن.
تجميع الخطافات
يمكن لخطافات متعددة مطابقة نفس الحدث. وفقًا لوثائق المرجع، يتم تنفيذ الخطافات بشكل متسلسل بترتيب التعريف. إذا منع أي خطاف العملية، فلن يتم تنفيذ الخطافات المتبقية.
هذا مهم للأداء. خمس خطافات متزامنة بسرعة 200 مللي ثانية لكل منها تضيف ثانية واحدة لكل حدث. دمج عمليات التحقق ذات الصلة في خطاف واحد يقلل من الحمل الزائد.
أنماط متقدمة
بالإضافة إلى الأتمتة الأساسية، تمكن الخطافات من تخصيص سير العمل المعقد.
سلاسل الخطافات ذات الحالة
يمكن للخطافات الاحتفاظ بالحالة بين عمليات التنفيذ باستخدام الملفات أو قواعد البيانات. قد يسجل خطاف PostToolUse العمليات الناجحة التي يتحقق منها خطاف PreToolUse لاحقًا:
| #!/bin/bash # Record successful edits echo “${toolInput.path}” >> .claude/edit-history.txt |
يمكن لخطاف PreToolUse مصاحب التحقق من هذا السجل لمنع العمليات المتكررة أو فرض قيود الترتيب.
التفعيل الشرطي للخطاف
تتحكم متغيرات البيئة في سلوك الخطافات في وقت التشغيل. تعيين CLAUDE_SKIP_HOOKS=1 يعطل الخطافات لحالات الطوارئ.
يمكن للخطافات نفسها التحقق من علامات البيئة:
| #!/bin/bash if [ “$STRICT_MODE” = “1” ]; then # Apply strict validation exit 1 fi exit 0 |
هذا يمكّن وضع التطوير مقابل وضع الإنتاج دون تغييرات التكوين.
التحقق متعدد المراحل
يمكن لخطافات PreToolUse تنفيذ التحقق متعدد المستويات حيث يسمح رمز الخروج 2 لـ Claude بالمتابعة مع التحذيرات:
- الفشل التام (رمز الخروج 1): منع العمليات الخطيرة
- تحذيرات خفيفة (رمز الخروج 2): تنبيه Claude لإعادة النظر
- المرور مع السياق (رمز الخروج 0 + JSON): توفير معلومات إضافية
هذا ينشئ طيفًا من التحقق أكثر دقة من ثنائي السماح / الرفض.
التكامل مع CI/CD
وفقًا للوثائق الرسمية لتكامل المنصة، يعمل Claude Code في بيئات CI/CD لمراجعة التعليمات البرمجية المؤتمتة وتصنيف المشكلات. توسع الخطافات هذه الأتمتة.
يمكن لسير عمل GitHub Actions تعريف الخطافات التي تفرض سياسات الفريق أثناء الجلسات المؤتمتة:
| – name: Run Claude Code with strict hooks env: STRICT_MODE: 1 run: | claude “Review this PR and suggest improvements” |
تنشط علامة 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 من الخطافات بدلاً من أوامر 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 استدعاء واجهات برمجة التطبيقات الداخلية خلف جدران الحماية؟
نعم، إذا كان Claude Code يعمل في بيئة لديها وصول شبكة إلى تلك الواجهات البرمجية. تقوم خطافات HTTP بإجراء طلبات POST قياسية من الجهاز الذي يقوم بتشغيل Claude Code. تنطبق جدران الحماية للشركات وشبكات VPN بشكل طبيعي. يتحكم وكيل الصندوق الرمل المذكور في الوثائق في التعرض لمتغيرات البيئة، وليس توجيه الشبكة.
هل تزيد الخطافات من استخدام Claude Code للرموز؟
تقوم خطافات المطالبات بحقن نص في سياق Claude، مما يستهلك رموزًا. لا تؤثر خطافات الأوامر و HTTP بشكل مباشر على استخدام الرموز، ولكن مخرجاتها (رسائل الخطأ، الاقتراحات) تصبح جزءًا من سياق المحادثة. يضيف رمز الخروج 2 مع رسائل توضيحية سياقًا أكثر من رمز الخروج 1 مع منع بسيط.
خاتمة
تحول خطافات Claude Code المساعد الذكي من أداة قوية إلى منصة تطوير مؤتمتة بالكامل. يوفر نظام الأحداث نقاط اعتراض طوال سير عمل Claude - من تهيئة الجلسة إلى ضغط السياق.
تتعامل خطافات الأوامر مع التحقق المحلي والتنسيق. تتكامل خطافات HTTP مع الخدمات وقواعد البيانات الخارجية. تعدل خطافات المطالبات السلوك من خلال حقن السياق. معًا، تتيح هذه الأنماط التي تفرض سياسات الفريق، وتحافظ على جودة التعليمات البرمجية، وتتكامل مع البنية التحتية للتطوير الحالية.
يقوم نظام المطابقة بتصفية الخطافات إلى أدوات وأنماط ملفات محددة. تتحكم رموز الخروج ومخرجات JSON في تدفق القرار. يمنع التنفيذ غير المتزامن الحظر في العمليات البطيئة. يدعم مخطط التكوين الكامل كل شيء بدءًا من التنسيق التلقائي البسيط إلى التحقق المعقد متعدد المراحل.
ابدأ بخطافات PostToolUse الأساسية لتنسيق التعليمات البرمجية. أضف التحقق PreToolUse مع ظهور السياسات. جرب خطافات المطالبات لتعديل السلوك. قم بإنشاء تكاملات HTTP لفرض سياسات على مستوى الفريق.
تحقق من الوثائق الرسمية لـ Claude Code للحصول على مرجع الخطافات الكامل ومخطط التكوين المحدث مع شحن القدرات الجديدة.
