ميزة متقدمة

Hooks: ابنِ لك سير العمل المخصص

أدرج منطقًا مخصصًا في كل مرحلة من استدعاءات أدوات Claude Code — تنسيق تلقائي، واختبار، ومراجعة، وتأمين — كلها مؤتمتة

#Hooks #Automation #ClaudeCode #CI/CD

ما هي Claude Code Hooks؟

Hooks هي نظام الأحداث في Claude Code الذي يتيح لك تشغيل نصوص shell مخصصة قبل استدعاءات الأدوات وبعدها. شغّل أدوات lint تلقائيًا بعد حفظ الملفات، أو نفّذ الاختبارات قبل عمليات commit، أو أطلق تنبيهات عند الوصول إلى ملفات حساسة — كل ذلك دون تدخل يدوي.

تتداخل الإعدادات على ثلاثة مستويات: الحدث، وmatcher يصفّي الأدوات، وبرنامجك النصي داخل مصفوفة hooks الداخلية. يقرأ البرنامج النصي JSON الخاص بهذا الحدث من stdin ويجيب برموز الخروج: 0 يعني عدم الاعتراض، و2 يحجب الاستدعاء في الأحداث التي تسمح بذلك. للأحداث الأربعة أدناه، يُلغى hook من نوع command عند بلوغ مهله الافتراضية البالغة 600 ثانية؛ وهذه الأربعة هي الشائعة، وليست القائمة الرسمية الكاملة (تم التحقق في 2026-09-22).

المستخدم

يرسل prompt

نقطة تحقق hook

يتحقق قبل تشغيل الأداة، ويمكنه الحجب

تشغيل الأداة

عندها فقط تُنفَّذ الأداة

شرح أنواع Hooks

تغطي Hooks في Claude Code نقاط دورة حياة الأداة والجلسة والضغط، مع معالجات command وHTTP وagent

PreToolUse: قبل استدعاء الأداة

يُفعّل قبل تنفيذ الأداة — تحقّق من المعاملات، وافحص الأذونات، ووافق تلقائيًا أو ارفض

"PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command" }] }]

PostToolUse: بعد استدعاء الأداة

يُفعّل بعد تنفيذ الأداة — تنسيق تلقائي، وتشغيل الاختبارات، وإرسال الإشعارات

"PostToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command" }] }]

Notification: عند الإشعارات

يُفعّل عند إشعارات Claude Code — تكامل مع Slack أو البريد الإلكتروني أو قنوات أخرى

"Notification": [{ "matcher": "permission_prompt", "hooks": [{ "type": "command" }] }]

Stop: عندما ينتهي Claude

يُفعّل عندما ينتهي Claude Code من الاستجابة — سجّل النتائج أو نفّذ التنظيف

"Stop": [{ "hooks": [{ "type": "command", "command": "~/scripts/on-stop.sh" }] }]

ثلاث حالات عملية للأتمتة

تتشارك الحالات الثلاث أدناه بنية واحدة: اختر الحدث، وضيقه باستخدام matcher، وضع البرنامج النصي في مصفوفة hooks الداخلية. تعرض المقتطفات النية فقط، لذا اجعل المرجع الرسمي هو المصدر لأسماء الحقول والتداخل، واقرأ من JSON على stdin كل ما يجب أن يتحقق منه برنامجك النصي.

نسّق قبل commit

عندما يكون Claude على وشك تشغيل git commit، يمرر PreToolUse الوسائط إلى برنامجك النصي أولًا. يكتشف البرنامج النصي أمر commit، ويشغّل أداة التنسيق، ويجيب برمز خروج: 0 يسمح بمرور الاستدعاء، و2 يحجبه. يحدث كل ذلك قبل التنفيذ، لذا فإن commit المحجوب يترك شجرة العمل دون تغيير.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "command": "if echo \"$TOOL_INPUT\" | grep -q 'git commit'; then npm run format; fi"
    }]
  }
}

أرسل إشعارًا عند انتهاء الاختبارات

لا يُفعَّل PostToolUse إلا بعد أن ينتهي أمر بنجاح، لذا يمكن لبرنامجك النصي رصد pytest أو npm test وإظهار إشعار سطح مكتب. لا يمكنه التراجع عن استدعاء نُفّذ بالفعل، ويلتزم الصمت عند حالات الفشل، لذا يعني الإشعار أن النتائج جاهزة، لا أن الاختبارات نجحت.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "command": "if echo \"$TOOL_INPUT\" | grep -q 'pytest\\|npm test'; then notify-send 'Tests completed'; fi"
    }]
  }
}

ارفض التعديلات على الملفات السرية

ضع hook من نوع PreToolUse على Edit وWrite: يأخذ البرنامج النصي المسار الهدف من stdin ويخرج بالرمز 2 عندما يطابق الاسم .env أو credentials أو ما شابه. تُرفض الكتابة قبل أن تلمس القرص، لذا لا يوجد ما يمكن التراجع عنه. يغطي matcher بالقيمة Edit|Write كلا الأداتين في آن واحد.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "command": "if echo \"$TOOL_INPUT\" | grep -qE '\\.env|credentials|secrets'; then exit 2; fi"
    }]
  }
}

وضع headless وCI/CD

شغّل Claude Code في خطوط أنابيب CI/CD باستخدام العلامة -p لمهام الأتمتة دون إشراف

-p للتشغيل غير التفاعلي

أضف الخيار -p (أو --print) إلى أي أمر claude لتشغيله بشكل غير تفاعلي وطباعة النتيجة عند الانتهاء.

مرّره إلى CI عبر pipe

يقرأ الوضع غير التفاعلي من stdin ويكتب النتيجة إلى stdout؛ ويعني رمز الخروج 0 النجاح، لذا يمكن لبرامج البناء النصية التفرع بناءً عليه.

إخراج منظّم باستخدام JSON

استخدم --output-format لاختيار شكل الاستجابة؛ يعيد json النتيجة مع معرّف الجلسة وبيانات وصفية، جاهزة لتحليلها بواسطة البرامج النصية.

استدعاء غير تفاعلي في CI

# شغّل مراجعة غير تفاعلية: إخراج JSON، بحد أقصى 5 جولات
claude -p "Review this PR and suggest improvements" \
  --output-format json \
  --max-turns 5

إعداد settings.json

عرّف Hooks الخاصة بك في .claude/settings.json

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "~/scripts/pre-bash-hook.sh"
      },
      {
        "matcher": "Edit|Write",
        "command": "~/scripts/protect-sensitive-files.sh"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "command": "~/scripts/post-bash-hook.sh"
      }
    ],
    "Notification": [
      {
        "command": "~/scripts/send-notification.sh"
      }
    ],
    "Stop": [
      {
        "command": "~/scripts/on-stop.sh"
      }
    ]
  }
}

أفضل ممارسات Hooks

تتبع هذه النقاط الأربع مرجع Claude Code Hooks، بما في ذلك ملاحظاته الأمنية، الذي تم التحقق منه في 2026-09-22؛ وهي تغطي كيفية كتابة النصوص البرمجية، بينما توجد بنية الإعداد في قسم settings.json أعلاه.

الحجب برمز الخروج 2

يقول المرجع إنه في معظم أحداث hook يكون رمز الخروج 2 هو الرمز الوحيد الذي يحجب من تلقاء نفسه؛ وأي رمز خروج آخر هو خطأ غير حاجب ويستمر الإجراء. أما النص البرمجي المخصص لفرض سياسة فيجب أن ينتهي برمز الخروج 2.

ضيّق المحفزات باستخدام matcher

يُرشّح حقل matcher وقت تفعيل Hooks. اسم الأداة المجرد يطابق تمامًا، بينما تُقيَّم القيمة التي تحتوي على أحرف أخرى كتعبير نمطي JavaScript غير مثبت: Edit.* يطابق كلاً من Edit وNotebookEdit، لذا أضف مثبتات لمطابقة السلسلة كاملة.

انتهاء المهلة ليس حجبًا

يلغي Claude Code أي hook يصل إلى مهلة التنفيذ ويتجاهل الإخراج، لذا في معظم الأحداث لا يصدر hook انتهت مهلته أي قرار. تحذّر الوثائق من أنه في PreToolUse لا يحجب hook من نوع command كهذا الاستدعاء، بينما في PreModelSwitch يحجب التبديل. وتحتفظ سجلات التصحيح بتفاصيل التنفيذ.

تعامل مع الإدخال على أنه غير موثوق

تسرد الملاحظات الأمنية بعض العادات: لا تثق أبدًا ببيانات الإدخال دون تمحيص، وضع متغيرات shell بين علامتي اقتباس دائمًا، وافحص اجتياز المسارات مثل ../ وتخطَّ الملفات الحساسة مثل .env أو .git. يقرأ hook حمولة JSON يمكن أن تحتوي حقولها على أي شيء من الخارج.

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

كيف يتلقى نص hook البرمجي JSON الإدخال؟

يتلقى hook من نوع command كائن JSON على stdin. تشمل الحقول الشائعة session_id وtranscript_path وcwd وhook_event_name؛ ثم يضيف كل حدث حقوله الخاصة، لذا تحمل أحداث الأدوات tool_name وtool_input.

كيف أجعل hook يحجب استدعاء أداة؟

اربط النص البرمجي بـ PreToolUse وأعد رمز الخروج 2 للاستدعاءات التي يجب ألا تُنفَّذ. يصنّف جدول الأحداث PreToolUse على أنه قابل للحجب، لذا يوقف رمز الخروج 2 ذلك الاستدعاء؛ ولاتخاذ قرار شرطي، اطبع JSON يتضمن permissionDecision بدلًا من ذلك. ولا يحجب رمز الخروج 1 شيئًا في معظم الأحداث.

ماذا يحدث عندما تنتهي مهلة hook؟

يُلغى أي hook يبلغ مهلة الانتظار الخاصة به وتُهمل مخرجاته، وهذا يعني في معظم الأحداث عدم اتخاذ أي قرار؛ أما PreModelSwitch فهو الحالة التي يؤدي فيها نفاد الوقت إلى منع التبديل. كما أن كتابة مسار البرنامج النصي بشكل خاطئ خطأ غير حاجب أيضًا، وتنصحك الوثائق بمراقبة هذا التنبيه عند أول تشغيل لـ hook خاص بالسياسة.

ما الملف الذي يحتوي على إعدادات Hooks؟

يتبع النطاق مكان تعريفه: يغطي ~/.claude/settings.json جميع مشاريعك ويبقى على جهازك؛ و.claude/settings.json خاص بكل مشروع ويمكن إضافته إلى المستودع؛ و.claude/settings.local.json خاص بكل مشروع ويُستثنى عبر gitignore عندما يحفظ Claude Code إعدادًا فيه.

أتمتة المؤسسات مع QCode.cc

اجمع منصة المطورين QCode.cc مع Hooks لبناء خطوط أنابيب برمجة بالذكاء الاصطناعي بمستوى المؤسسات

الوصول عبر البوابة باستخدام ANTHROPIC_BASE_URL

يقول المرجع الرسمي لمتغيرات البيئة في Claude Code إن ANTHROPIC_BASE_URL يمكنه توجيه نقطة نهاية API إلى وكيل أو بوابة؛ وتنشر QCode دليل إعداد لهذا المسار على الموقع (تم التحقق في 2026-09-22).

المكابح قبل الأتمتة

ضع المكابح قبل الأتمتة: يُظهر المثال الرسمي برنامجًا نصيًا يتحقق من المسار الهدف مقابل أنماط محمية ويخرج بالرمز 2 لحجب التعديلات على الملفات الحساسة.

إعداد واحد للفريق بأكمله

يقول جدول مواقع hook الرسمي إن .claude/settings.json يمكن إضافته إلى المستودع؛ واقرنه بمفتاح QCode واحد مشترك بين الفريق لتتصرف Hooks لدى الجميع بالطريقة نفسها.

خطة واحدة، ثلاث منصات

QCode يدعم أيضًا OpenAI Codex / GPT-5.6

تعمل حصتك في QCode عبر Claude Code وOpenAI Codex CLI — رصيد واحد مشترك، دون أي إنفاق مكرر.

دليل Codex CLI فعّل GPT-5.6

أتمِت سير عمل Claude Code الخاص بك

أطلق العنان لكامل إمكانات البرمجة بالذكاء الاصطناعي مع Hooks + QCode.cc

عرض الخطط عرض الوثائق

وثائق متعمقة

شرح معمّق لنظام Hooks

17 نوعًا من الأحداث، و10 وصفات تطبيقية، وإعداد بمستوى المؤسسات

الأتمتة وCI/CD

5 أمثلة تطبيقية على GitHub Actions، وعزل Docker

آخر تحديث 2026-11-14