خطافات Claude Code في 2026: دليل عملي وتطبيقي

خطافات Claude Code هي أوامر طرفية (shell) أو استدعاءات HTTP أو مطالبات لنماذج اللغة يعرّفها المستخدم وتُنفَّذ تلقائيًا عند نقاط ثابتة في دورة حياة Claude Code: قبل تشغيل أداة، أو بعد تحرير ملف، أو عند بدء جلسة، أو عند انتهاء Claude من دوره. وهي موجودة لجعل إجراءات معيّنة حتمية. فبدلًا من الأمل في أن يتذكر النموذج تنسيق شفرتك أو تجنّب أمر مدمّر، يفرض الخطاف القاعدة في كل مرة. يغطّي هذا الدليل ما هي خطافات Claude Code، والأحداث التي تُطلَق عندها، وكيفية إعداد أول خطاف لك، ومثالًا عمليًا يمكنك نسخه، ومتى تلجأ إلى خطاف بدلًا من مهارة أو وكيل فرعي.

نحن نُشغّل خط إنتاج المحتوى لهذا الموقع على Claude Code، لذا فإن الخطافات جزء من أدواتنا اليومية. الأنماط التالية هي التي يجدر تعلّمها أولًا.

ما هي خطافات Claude Code؟

الخطاف قاعدة تفرضها الشفرة بدلًا من التعليمات. فكل ما تضعه في ملف CLAUDE.md أو في مطالبة هو اقتراح يمكن للنموذج، من حيث المبدأ، أن يتجاهله أو ينساه. أما الخطاف فليس اختياريًا: فعندما يُطلَق الحدث، يعمل الخطاف، ولا نقاش. ووفق توثيق الخطافات من Anthropic، فإن الخطاف هو «أمر طرفية أو نقطة نهاية HTTP أو مطالبة لنموذج لغة يعرّفها المستخدم وتُنفَّذ تلقائيًا عند نقاط محددة في دورة حياة Claude Code».

هذا التمييز هو جوهر الأمر. فإذا أردت تشغيل أداة الفحص (linter) بعد كل تعديل، فإن مطالبة تقول «شغّل أداة الفحص دائمًا» تنجح في معظم الأحيان؛ أما خطاف PostToolUse فيشغّلها في كل مرة، دون الاعتماد على تقدير النموذج. الخطافات هي الطريقة التي تحوّل بها «عادةً ما يفعل Claude كذا» إلى «دائمًا ما يفعل Claude كذا». ومن المهام الشائعة التنسيق التلقائي للملفات، وحظر أوامر الطرفية الخطرة، وإرسال إشعار على سطح المكتب عندما يحتاج Claude إلى إدخال، وحقن سياق جديد (مثل فرع git الحالي) عند بدء الجلسة.

متى تُطلَق الخطافات: أحداث دورة الحياة

يوفّر Claude Code أكثر من ثلاثين حدثًا في دورة الحياة يمكنك الارتباط بها، لكن حفنة منها تغطّي تقريبًا كل حالة استخدام واقعية. ويمرّر كل حدث إلى خطافك حمولة JSON عبر stdin تصف ما يجري.

الحدث	يُطلَق عندما	الاستخدام النموذجي
UserPromptSubmit	ترسل مطالبة، قبل أن يقرأها Claude	حقن السياق، حظر الأسرار في المطالبة
PreToolUse	قبل تشغيل أي أداة	حظر أمر أو التحكم فيه؛ ويمكنه رفض الإجراء
PostToolUse	بعد نجاح أداة	تنسيق الشفرة، تشغيل الاختبارات، الفحص
SessionStart	تبدأ جلسة أو تُستأنف	تحميل سياق الفرع أو التذكرة أو البيئة
Stop	ينتهي Claude من الرد	فرض «يجب أن تنجح الاختبارات قبل أن تتوقف»
SubagentStop	ينتهي وكيل فرعي	التحقق من مخرجات وكيل فرعي
Notification	يرسل Claude إشعارًا	تنبيهات سطح المكتب عند الحاجة إلى إدخال

الحدثان اللذان ستستخدمهما أكثر من غيرهما هما PreToolUse (لمنع حدوث الأشياء) وPostToolUse (للتفاعل بعد حدوثها). ويتيح حقل matcher لكل خطاف أن يستهدف أدوات بعينها، فينطلق المنسّق مثلًا عند Edit وWrite فقط، بينما ينطلق حارس الأوامر عند Bash فقط.

كيفية إعداد أول خطاف لك

تعيش الخطافات في كتلة hooks داخل ملف إعدادات. والمكان الذي تضع فيه ذلك الملف يحدّد نطاقه:

الملف	النطاق	قابل للمشاركة
~/.claude/settings.json	كل مشروع على جهازك	لا
.claude/settings.json	مشروع واحد	نعم، أودعه في المستودع
.claude/settings.local.json	مشروع واحد، خاص	لا، مستبعَد عبر gitignore

تتداخل البنية على ثلاثة مستويات: الحدث، ومجموعة matcher التي تصفّي الأدوات التي ينطبق عليها، والمعالِج الذي يقوم بالعمل الفعلي. وإليك خطاف إشعار سطح المكتب من دليل الإعداد الخاص بـ Anthropic، وهو ينبّهك كلما كان Claude في انتظارك:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "notify-send 'Claude Code' 'Waiting for your input'" }
        ]
      }
    ]
  }
}

أضِف ذلك إلى .claude/settings.json، وأعِد تشغيل الجلسة، فيصبح الخطاف فعّالًا. والمطابِق الفارغ يعني «طابِق كل شيء». هذا هو النموذج الذهني بأكمله: اختَر حدثًا، وضيّقه اختياريًا بمطابِق، ووجّهه إلى أمر.

مثال عملي: تنسيق التعديلات وحظر الأوامر الخطرة

يثبت خطافان جدواهما في كل مشروع تقريبًا. الأول ينسّق كل ملف يلمسه Claude؛ والثاني يرفض تشغيل أوامر الطرفية المدمّرة.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write \"$CLAUDE_FILE_PATHS\" 2>/dev/null || true" }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh" }
        ]
      }
    ]
  }
}

حارس PreToolUse هو سكربت صغير يقرأ الأمر المقترح ويقرّر ما إذا كان سيسمح به. وهنا تهمّ رموز الخروج: فالخروج بالرمز 0 يعني «لا اعتراض، تابِع»، بينما الخروج بالرمز 2 خطأ حاجب يوقف الأداة ويعيد رسالتك إلى Claude. ويمكنك أيضًا طباعة JSON مُنظَّم لتحكّم أدق:

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')
if echo "$COMMAND" | grep -qE 'rm -rf|:(){:|:&};:'; then
  jq -n '{ hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "deny",
    permissionDecisionReason: "Destructive command blocked by project hook"
  }}'
  exit 0
fi
exit 0

الآن لا يستطيع Claude فعليًا تشغيل rm -rf في هذا المشروع، ويخرج كل ملف مُحرَّر منسَّقًا، دون أن يعتمد أيٌّ من السلوكين على تذكّر النموذج للقيام بذلك.

الخطافات المبنية على المطالبة والمبنية على الوكيل (جديدة في 2026)

ليست كل قاعدة إجابةً واضحة بنعم/لا يمكنك التعبير عنها في سكربت طرفية. أضافت Anthropic نوعين من الخطافات في 2026 للقرارات التي تتطلّب تقديرًا. فالخطاف المبني على المطالبة (type: "prompt") يرسل مُدخَل الخطاف إلى نموذج Claude، وهو Haiku افتراضيًا، ويترك للنموذج إعادة القرار، وهو مفيد لشيء مثل «احظر رسالة الإيداع هذه إن سرّبت اسم عميل». أما الخطاف المبني على الوكيل (type: "agent") فيُطلق وكيلًا فرعيًا للتحقق من أمر أكثر تعقيدًا قبل أن يتابع Claude. وكلاهما يستبدل بحتمية أمر الطرفية مرونةً، وكلاهما يكلّف استدعاءً للنموذج، فاحتفظ بهما للحالات التي يعجز التعبير النمطي (regex) عن التعامل معها فعلًا. أما الغالبية العظمى من الخطافات، فإن أمر command بسيطًا أسرع ومجاني وقابل للتنبؤ تمامًا.

الخطافات مقابل المهارات والوكلاء الفرعيين وCLAUDE.md

يمنحك Claude Code عدة نقاط توسّع، والخطأ الشائع هو استخدام النقطة الخاطئة. والخط الفاصل هو الحتمية.

• الخطافات تفرض قاعدة بالشفرة. استخدمها عندما يجب أن يحدث شيء في كل مرة، بصرف النظر عمّا يقرّره النموذج: التنسيق، والحواجز الوقائية، والإشعارات، وحقن السياق.
• المهارات تمنح Claude تعليمات وسكربتات قابلة لإعادة الاستخدام يختار تطبيقها عندما يطابق الموقف. فهي توسّع القدرة لا الإلزام.
• الوكلاء الفرعيون ينفّذون العمل في سياق معزول كي لا تُغرق مهمة كبيرة الخيط الرئيسي. فهم متعلقون بالسياق لا بالقواعد.
• CLAUDE.md توجيه دائم يقرأه النموذج ويتّبعه عادةً، لكن يمكنه تجاوزه.

إذا ظلّت تعليماتك تُتجاهَل مرارًا، فتلك إشارة إلى ترقيتها من سطر في CLAUDE.md إلى خطاف. وتتلاءم الخطافات أيضًا بطبيعتها مع خوادم MCP: إذ يمكن لخطاف أن يستدعي أداة MCP، أو أن يُطلَق عند استخدام أداة MCP، لربط Claude بأنظمتك القائمة.

هل هي آمنة؟ تعمل الخطافات بكامل صلاحياتك

نعم، مع تحفّظ جدّي واحد: تنفّذ الخطافات أوامر عشوائية على جهازك بصلاحيات مستخدمك، تلقائيًا ودون طلب تأكيد. ودليل Anthropic صريح في أنك المسؤول الوحيد عمّا تفعله خطافاتك، وأن خطافًا متهاونًا قد يحذف ملفات أو يُتلف بيانات. لا تلصق أبدًا إعداد خطاف من مصدر غير موثوق دون قراءة كل أمر أولًا، واحتفظ بالخطافات المشتركة في .claude/settings.json مُودَع كي يتمكن زملاؤك من مراجعتها، وفضّل الحرّاس الحاجبين على أي شيء يكتب أو يحذف من تلقاء نفسه. تعامل مع الخطاف كما تتعامل مع أي سكربت يعمل دون إشراف.

الأسئلة الشائعة

فيمَ يمكنك استخدام خطافات Claude Code؟

أكثر الاستخدامات شيوعًا هي التنسيق والفحص التلقائيان بعد التعديلات، وحظر الأوامر الخطرة أو المخالِفة للسياسة، وتشغيل الاختبارات قبل أن ينهي Claude دوره، وإرسال إشعارات سطح المكتب عندما يحتاج Claude إلى إدخال، وحقن السياق (فرع git، رقم التذكرة، البيئة) عند بدء الجلسة.

ما الفرق بين الخطاف وقاعدة CLAUDE.md؟

قاعدة CLAUDE.md توجيه يقرأه النموذج ويتّبعه عادةً لكنه قد يتجاهله أو ينساه. أما الخطاف فتفرضه الشفرة ويعمل في كل مرة يُطلَق فيها حدثه. استخدم CLAUDE.md للتفضيلات، والخطافات لكل ما يجب ضمانه.

كم عدد أحداث الخطافات، وأين القائمة الكاملة؟

يوفّر Claude Code أكثر من ثلاثين حدثًا في دورة الحياة، من SessionStart إلى PreToolUse وPostToolUse وStop وأحداث الوكلاء الفرعيين. وتوجد القائمة الكاملة والمحدَّثة مع مخططات الإدخال والإخراج في مرجع الخطافات الرسمي.

هل تُبطئ الخطافات Claude Code؟

خطافات الأوامر سريعة عادةً، وتعمل كل الخطافات المطابِقة على التوازي، فيكون العبء صغيرًا. أما الخطافات المبنية على المطالبة والمبنية على الوكيل فتضيف استدعاءً للنموذج وهي أبطأ، فاحتفظ بها للقرارات التي لا يستطيع سكربت الطرفية اتخاذها.

المصادر

• Claude Code Docs — مرجع الخطافات: القائمة الرسمية لأحداث دورة الحياة، وبنية الإعداد، والمطابِقات، ومخطط الإدخال، ورموز الخروج، وحقول إخراج JSON.
• Claude Code Docs — أتمتة الإجراءات بالخطافات (دليل): جولة في الخطاف الأول، والخطافات المبنية على المطالبة والمبنية على الوكيل، والتحذير الأمني بأن الخطافات تعمل بصلاحياتك.