Claude Code: نظام الخطافات

آخر تحديث: 2026-08-31

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

💡 نصيحة: الخطافات هي "معترضات" في دورة حياة Claude Code — تنفّذ سكربتات مخصصة عند حدوث أحداث محددة، لتنفيذ سير عمل آلي.

📋 المتطلبات السابقة: الفصل 17 - أنماط الإخراج

1. ما ستتعلمه


2. دورة حياة الخطافات

(1) أنواع الأحداث

الحدث وقت التفعيل الاستخدام الشائع
before:prompt قبل معالجة إدخال المستخدم معالجة مسبقة للإدخال
before:tool:write قبل كتابة الملف نسخ احتياطي تلقائي
after:tool:write بعد كتابة الملف تنسيق تلقائي
before:tool:bash قبل تنفيذ الأمر فحص أمني
after:tool:bash بعد تنفيذ الأمر معالجة لاحقة للنتيجة
after:استجابة بعد توليد الاستجابة إرسال إشعار

(2) سياق الخطاف

كل خطاف يستقبل كائن سياق يتضمن اسم الحدث، والطابع الزمني، ومسار الملف، والأمر، والمحتوى، ومعرّف الجلسة.

▶ مثال 1: تدفق تفعيل الخطافات

TEXT 📖 للعرض فقط
> Modify src/auth/jwt.ts

الخطافات المُفعّلة:
1. [before:tool:write] → نسخ احتياطي تلقائي لـ jwt.ts
2. [تمت كتابة الملف]
3. [after:tool:write] → تشغيل ESLint --fix
4. [before:tool:bash] → فحص أمان الأمر
5. [تنفيذ: npm test]
6. [after:tool:bash] → تحليل نتائج الاختبار
7. [after:response] → إرسال إشعار Slack

3. تهيئة الخطافات

(1) تهيئة الخطافات العامة

JSON
// ~/.claude/hooks.json
{
  "hooks": {
    "before:tool:write": [
      {
        "name": "auto-backup",
        "command": "cp ${filePath} ${filePath}.bak",
        "enabled": true
      }
    ],
    "after:tool:write": [
      {
        "name": "auto-format",
        "command": "npx prettier --write ${filePath}",
        "enabled": true
      }
    ]
  }
}

(2) خطافات على مستوى المشروع

JSON
// .claude/hooks.json
{
  "hooks": {
    "before:tool:write": [
      {
        "name": "protect-config",
        "condition": "filePath.endsWith('.env')",
        "command": "echo 'Config file modification blocked' && exit 1",
        "enabled": true
      }
    ]
  }
}

4. سيناريوهات عملية

▶ مثال 2: خطاف النسخ الاحتياطي التلقائي

JSON
{
  "hooks": {
    "before:tool:write": [
      {
        "name": "git-backup",
        "command": "git stash push -m 'auto-backup-before-claude' -- ${filePath} 2>/dev/null || true",
        "enabled": true
      }
    ]
  }
}

▶ مثال 3: خطاف التدقيق الأمني

JSON
{
  "hooks": {
    "before:tool:bash": [
      {
        "name": "block-dangerous-commands",
        "condition": "command.includes('rm -rf') || command.includes('DROP TABLE')",
        "command": "echo '⚠️ Dangerous command blocked' && exit 1",
        "enabled": true
      }
    ]
  }
}

▶ مثال 4: خطاف الاختبار التلقائي

JSON
{
  "hooks": {
    "after:tool:write": [
      {
        "name": "auto-test",
        "condition": "filePath.includes('src/') && filePath.endsWith('.ts')",
        "command": "npm test 2>&1 | tail -5",
        "enabled": true
      }
    ]
  }
}

5. تنقيح الخطافات

BASH
# تفعيل تنقيح الخطافات
export CLAUDE_HOOK_DEBUG=1

# عرض سجلات تنفيذ الخطافات
cat ~/.claude/hooks.log

# تعطيل جميع الخطافات مؤقتاً
claude --no-hooks

(1) المشكلات الشائعة

المشكلة السبب الحل
الخطاف لا يتفعّل enabled: false تحقق من التهيئة
أخطاء في الخطاف مشاكل مسار الأمر استخدم مسارات مطلقة
الخطاف بطيء وقت تنفيذ السكربت اجعله غير متزامن أو بسّط المنطق
تفعيل حلقي الخطاف يُفعّل خطافاً آخر أضف شروطاً لتجنب ذلك

6. مثال شامل: حل خطافات كامل

JSON
{
  "hooks": {
    "before:tool:write": [
      {
        "name": "auto-backup",
        "command": "cp ${filePath} /tmp/claude-backup/$(basename ${filePath}).$(date +%s)",
        "enabled": true
      },
      {
        "name": "protect-env",
        "condition": "filePath.endsWith('.env')",
        "command": "echo '❌ Env file modification blocked' && exit 1",
        "enabled": true
      }
    ],
    "after:tool:write": [
      {
        "name": "format",
        "command": "npx prettier --write ${filePath} 2>/dev/null; npx eslint --fix ${filePath} 2>/dev/null; true",
        "enabled": true,
        "files": ["src/**/*.ts"]
      }
    ],
    "before:tool:bash": [
      {
        "name": "block-dangerous",
        "condition": "command.match(/rm -rf|DROP|npm publish/)",
        "command": "echo '⛔ Dangerous command blocked' && exit 1",
        "enabled": true
      }
    ]
  }
}

❓ أسئلة شائعة

س هل تُبطئ الخطافات Claude Code؟
ج نعم. كل خطاف ينفّذ أمراً؛ والخطافات البطيئة تؤثر بشكل ملحوظ على التجربة. أبقِ سكربتات الخطافات أقل من ثانية واحدة.
س هل فشل الخطاف يمنع العمليات؟
ج خطافات before الفاشلة (exit 1) تمنع العمليات؛ وفشل خطافات after لا يؤثر على العمليات المكتملة.
س هل يمكن للخطافات تعديل إخراج Claude Code؟
ج لا. الخطافات تنفّذ تأثيرات جانبية فقط (نسخ احتياطي، تنسيق، إشعار)، ولا تغيّر المحتوى المُعاد.
س خطاف أم إضافة؟
ج الخطافات استجابات أحداث خفيفة (تنفيذ أوامر)؛ والإضافات توسيعات وظيفية كاملة (تسجيل أدوات، تعديل سلوك). احتياجات بسيطة: خطافات؛ واحتياجات معقدة: إضافات.

📖 ملخص


📝 تمارين

  1. أساسي (⭐): هيّئ خطاف after:tool:write يشغّل Prettier تلقائياً عند تعديل الملفات.
  2. متوسط (⭐⭐): هيّئ خطافات أمنية لمنع rm -rf و npm publish.
  3. متقدم (⭐⭐⭐): صمّم حل خطافات كامل يغطي النسخ الاحتياطي والتنسيق والفحص الأمني والإشعارات.
Web-Tutorial.com

فريق Web-Tutorial التقني

منصة دروس برمجية يديرها عدة مطورين. كل درس يتم كتابته ومراجعته بواسطة مطورين متخصصين في المجال. نعمل على ضمان دقة وموثوقية المحتوى — إذا لاحظت أي مشكلة، فيرجى إخبارنا.

100%