دليل Claude Code Hooks: الدليل الشامل للمطورين مع أمثلة جاهزة للإنتاج

دليل Claude Code Hooks: الدليل الشامل للمطورين مع أمثلة جاهزة للإنتاج

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

لقد كنت أُعدّ الهوكس في عشرات المشاريع خلال الأشهر القليلة الماضية، وأصبحت بهدوء أهم جزء في إعداد Claude Code لديّ. يغطي هذا الدليل كل شيء من الأساسيات إلى حزمة بداية جاهزة للإنتاج يمكنك إضافتها إلى أي مشروع اليوم. إذا كنت قد استخدمت Claude Code إلى جانب أدوات مثل Cursor أو Copilot، فأنت تعرف قيمة التخصيص بالفعل -- والهوكس تأخذ ذلك خطوة أبعد.

ما هي هوكس Claude Code (ولماذا يجب أن تهتم بها)؟

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

مشكلة الاحتمالية

إليك المشكلة مع تعليمات CLAUDE.md: إنها اقتراحات، ليست عقودًا. يمكنك كتابة "شغّل دائمًا npx prettier --write بعد تحرير ملفات TypeScript" في سياق مشروعك، وسيتبعها Claude في معظم الأوقات. لكن "معظم الأوقات" ليس كافيًا عندما تطبّق تنسيق الكود عبر فريق كامل، أو تحظر الدفع إلى الإنتاج، أو تسجّل كل أمر shell لتدقيق أمني.

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

كيف تحل الهوكس هذه المشكلة

تتجاوز الهوكس نموذج اللغة كليًا. إنها نصوص shell، أو استدعاءات HTTP، أو تقييمات ذكاء اصطناعي تنطلق عند أحداث دورة حياة محددة -- قبل تشغيل أداة (PreToolUse)، وبعد اكتمالها (PostToolUse)، وعند ظهور إشعار، وعند بدء جلسة، وعندما يتوقف Claude. فكّر فيها مثل هوكس Git، لكن لمساعد الترميز بالذكاء الاصطناعي.

توجد أربعة أنواع من الهوكس: command (نصوص shell)، وHTTP (طلبات POST للـwebhook)، وprompt (تقييمات نعم/لا من Claude بدورة واحدة)، وagent (يُولّد وكيلًا فرعيًا بصلاحيات الأدوات). سنشرح كل واحدة لاحقًا -- تعالج هوكس command قرابة 90% مما ستحتاجه.

كيف تعمل هوكس Claude Code: تدفق دورة الحياة

تُنفَّذ هوكس Claude Code في دورة حياة محددة: يُطلق حدث (مثل PreToolUse)، يتحقق المُطابق هل تنطبق الهوك، يُشغَّل نص الهوك ويستقبل JSON عبر stdin، ويحدد رمز الخروج ما يحدث بعد ذلك. رمز الخروج 0 يعني المتابعة، ورمز الخروج 2 يعني حظر الإجراء. هذا التدفق هو نفسه بغض النظر عن نوع الهوك الذي تستخدمه.

الحدث -> المُطابق -> الهوك -> رمز الخروج (التدفق بـ4 خطوات)

إليك كيفية عمل كل تنفيذ للهوك:

1. يُطلق الحدث          مثلًا: PreToolUse(Write)
       |
2. يتحقق المُطابق       هل يُطابق "Write" نمط مُطابق الهوك؟
       |
3. تُنفَّذ الهوك         يُشغَّل نص shell، يستقبل JSON عبر stdin
       |
4. يقرر رمز الخروج      0 = متابعة | 2 = حظر | غير ذلك = خطأ

يحتوي JSON الذي يصل عبر stdin على كل شيء عن الحدث: اسم الأداة tool_name، ومدخلات الأداة tool_input (مسار الملف، المحتوى، الأمر)، وبيانات الجلسة. يقرأ نصك هذا JSON، وينفّذ أي منطق يحتاجه، ويخرج بالرمز المناسب.

بالنسبة لهوكس PreToolUse، رمز الخروج 2 هو الأقوى -- فهو يحظر الإجراء كليًا ويُرسل رسالة stdout إلى Claude كتغذية راجعة. يرى Claude رسالتك ويمكنه تعديل نهجه.

نطاقات الإعداد: User وProject وLocal

تعيش الهوكس في settings.json على ثلاثة مستويات:

إعدادات المشروع هي الأكثر فائدة للفرق. ضع هوكسك في .claude/settings.json، احفظها، وسيحصل كل مطوّر في الفريق على نفس الضمانات تلقائيًا.

حقل if: التصفية الدقيقة

منذ Claude Code الإصدار v2.1.85، تدعم الهوكس حقل if الذي يتيح لك التصفية حسب وسيطات الأداة -- وليس فقط أسماء الأدوات. كما هو موثّق في مرجع هوكس Anthropic، هذا يعني أنك تستطيع كتابة هوك تُطلَق فقط على أوامر Bash المطابقة لـgit push، بدلًا من إطلاقها على كل استدعاء Bash.

{
  "matcher": "Bash",
  "if": "tool_input.command matches 'git push'",
  "hooks": [{ "type": "command", "command": "./scripts/check-branch.sh" }]
}

كان هذا تغييرًا جذريًا. قبل if، كنت إما تُطابق على نطاق واسع جدًا (كل أمر Bash) أو تُجري التصفية داخل نصك (فوضى).

جدول مرجعي سريع لجميع أحداث هوكس Claude Code

يوفر Claude Code أكثر من 20 حدثًا عبر دورة حياته، كما هو موثّق في مرجع الهوكس الرسمي وسجل تغييرات Claude Code. الأكثر استخدامًا هي PreToolUse وPostToolUse وNotification وStop -- لكن الأحداث الجديدة مثل ConfigChange وFileChanged تفتح أنماط أتمتة متقدمة.

إليك المرجع الكامل:

نصيحة احترافية: ستستخدم PreToolUse وPostToolUse لـ80% من هوكسك. SessionStart هي الأكثر فائدة بعد ذلك -- مثالية لإدخال سياق المشروع الذي يحتاجه Claude في بداية كل جلسة.

شرح أنواع هوكس Claude Code الأربعة

يدعم Claude Code أربعة أنواع من مُعالجات الهوكس: تُشغّل هوكس command نصوص shell، وترسل هوكس HTTP طلبات POST إلى URLs، وتطرح هوكس prompt على Claude سؤالًا بنعم/لا، وتُولّد هوكس agent وكيلًا فرعيًا بصلاحيات الأدوات. من واقع تجربتنا، تعالج هوكس command 90% من حالات الاستخدام. استخدم HTTP للتكاملات الخارجية، واستخدم هوكس prompt وagent للقرارات الدقيقة التي تحتاج حكم الذكاء الاصطناعي.

هوكس Command (الحصان العامل)

تُشغّل هوكس command أمر shell وتستخدم رمز الخروج لتحديد النتيجة. تستقبل بيانات JSON للحدث عبر stdin.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.command' | grep -q 'rm -rf /' && exit 2 || exit 0"
      }]
    }]
  }
}

هذا ما ستستخدمه للتنسيق وحماية الملفات والإشعارات ومعظم الأتمتة. سريع وبسيط وقابل للتنبؤ.

هوكس HTTP (التكاملات الخارجية)

ترسل هوكس HTTP طلب POST إلى URL مع JSON الحدث كجسم. يحدد رمز حالة الاستجابة النتيجة (200 = متابعة، 403 = حظر).

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "http",
        "url": "https://your-api.com/claude-webhook"
      }]
    }]
  }
}

مثالي لإرسال الأحداث إلى Slack أو Discord أو PagerDuty أو لوحة تحكم مخصصة. يمكنك أيضًا استخدامها للاستعلام عن محرك سياسات خارجي قبل السماح بتنفيذ أداة.

هوكس Prompt (قرارات مدعومة بالذكاء الاصطناعي)

تُمرّر هوكس prompt بيانات الحدث إلى Claude نفسه لتقييم نعم/لا بدورة واحدة. يُعيد Claude استجابة JSON بـ"decision": "allow" أو "decision": "block" مع التفسير.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "prompt",
        "prompt": "Is this bash command safe to run in a production environment? Consider: does it modify system files, delete data, or access sensitive credentials?"
      }]
    }]
  }
}

استخدم هذه باعتدال. تُضيف زمن استجابة (استدعاء LLM كامل لكل تنفيذ هوك) وتكلفة. لكن لفحوصات الأمان الذاتية حقًا -- مثل "هل تبدو هجرة قاعدة البيانات هذه مدمّرة؟" -- يصعب التفوق عليها. إذا كنت مهتمًا بـتغيير نماذج Claude Code، فإن النموذج المستخدم لهوكس prompt يتبع نموذج جلستك الحالية.

هوكس Agent (التحقق بمساعدة الأدوات)

تُولّد هوكس agent وكيلًا فرعيًا بصلاحيات أدوات Read وGrep وGlob. يمكن للوكيل الفرعي فحص الملفات قبل اتخاذ قراره.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write",
      "hooks": [{
        "type": "agent",
        "prompt": "Check if the file being written follows the project's naming conventions and import patterns. Read .claude/CONVENTIONS.md for the rules."
      }]
    }]
  }
}

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

7 أمثلة على هوكس Claude Code جاهزة للإنتاج (قابلة للنسخ واللصق)

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

كل مثال أدناه هو مقتطف settings.json كامل يمكنك إضافته إلى .claude/settings.json. مجموعات المجتمع مثل awesome-claude-code لديها المزيد من الأنماط.

1. التنسيق التلقائي عند الحفظ

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }]
  }
}

يُطلَق هذا بعد كل Write أو Edit، ويستخرج مسار الملف من JSON في stdin، ويُشغّل المُنسّق المناسب. exit 0 في النهاية يضمن ألا تحظر الهوك أبدًا -- أخطاء التنسيق لا ينبغي أن توقف Claude.

نصيحة احترافية: أضف *.go مع gofmt و*.rs مع rustfmt إذا كنت تعمل عبر لغات متعددة.

2. حظر الكتابة على الملفات المحمية

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\.local|package-lock\\.json|yarn\\.lock|pnpm-lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: This file is protected. Edit it manually.\"}' && exit 2"
      }]
    }]
  }
}

رمز الخروج 2 يحظر الإجراء ويُرسل رسالة JSON إلى Claude. يرى Claude التغذية الراجعة ويتكيف -- عادةً سيخبرك أنه أراد تعديل الملف ويطلب منك فعل ذلك يدويًا. يمنع حقل if إطلاق الهوك على كل Write.

3. إشعار سطح المكتب عند الاكتمال

{
  "hooks": {
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Claude Code task finished\"' /dev/stdin); if [ \"$(uname)\" = 'Darwin' ]; then osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\"; else notify-send 'Claude Code' \"$MSG\"; fi; exit 0"
      }]
    }]
  }
}

يعمل على macOS (osascript) وLinux (notify-send). المُطابق الفارغ يعني إطلاقه على جميع الإشعارات. هذا مفيد حقًا عندما تُطلق مهمة طويلة وتنتقل إلى نافذة أخرى.

4. إدخال السياق عند بدء الجلسة

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null || echo none)\"' | Last commit: '\"$(git log --oneline -1 2>/dev/null || echo none)\"'\"}'; exit 0"
      }]
    }]
  }
}

يُدخل هذا اسم المشروع الحالي وفرع Git وآخر commit في كل جلسة. يستقبل Claude هذا السياق تلقائيًا -- لا حاجة لإخباره بأي فرع تعمل عليه.

5. تشغيل الاختبارات تلقائيًا بعد تغييرات الكود

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '\\.(ts|tsx|js|jsx|py)$'",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path' /dev/stdin); TEST_FILE=$(echo \"$FILE\" | sed 's/\\.[^.]*$/.test&/'); if [ -f \"$TEST_FILE\" ]; then npx jest \"$TEST_FILE\" --no-coverage 2>&1 | tail -5; fi; exit 0",
        "timeout": 30000
      }]
    }]
  }
}

إذا وجد ملف اختبار مطابق، يُشغَّل تلقائيًا بعد تحرير Claude للكود المصدر. tail -5 يُبقي المخرجات موجزة، والـtimeout يمنع مجموعات الاختبار الجامحة. يتوافق هذا جيدًا مع سير عمل مراجعة الكود بالذكاء الاصطناعي.

6. فرض حماية الفروع (متقدم)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "if": "tool_input.command matches 'git push.*(main|master|production)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"BLOCKED: Direct push to protected branch. Use a feature branch and open a PR.\"}' && exit 2"
      }]
    }]
  }
}

يحظر هذا أي git push يستهدف الفروع main أو master أو production. يتلقى Claude التغذية الراجعة ويقترح إنشاء فرع ميزة بدلًا من ذلك.

7. تسجيل تدقيق الأمان (متقدم)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "INPUT=$(cat /dev/stdin); CMD=$(echo \"$INPUT\" | jq -r '.tool_input.command'); echo \"[$(date -u +%Y-%m-%dT%H:%M:%SZ)] BASH: $CMD\" >> .claude/audit.log; exit 0"
      }]
    }]
  }
}

يسجّل كل أمر Bash ينفّذه Claude في ملف تدقيق مع طابع زمني بتوقيت UTC. لا يُقدَّر بثمن لمراجعات الأمان وفهم ما فعله Claude بالفعل خلال الجلسة. احتفظ بـ.claude/audit.log في .gitignore.

هوكس مقابل MCP مقابل Skills مقابل CLAUDE.md: متى تستخدم أيًا منها؟

استخدم الهوكس للأتمتة الحتمية التي يجب أن تُشغَّل دائمًا (التنسيق، الحظر، الإشعارات). استخدم MCP لمنح Claude وصولًا إلى أدوات وبيانات خارجية. استخدم Skills لحزم المطالبات القابلة لإعادة الاستخدام. استخدم CLAUDE.md للتوجيه السلوكي وسياق المشروع. الهوكس مضمونة؛ كل شيء آخر احتمالي. هذا هو التمييز الأهم من بعيد، وأجد نفسي أعود إليه باستمرار عند تقديم المشورة للفرق.

مصفوفة القرار

للتعمق في MCP، راجع دليل MCP. إذا كنت قادمًا من Cursor، نظام قواعد Cursor مماثل تقريبًا لـCLAUDE.md -- لكن Cursor لا يملك شيئًا يشبه الهوكس.

عندما تتداخل (وكيف تختار)

إليك مخطط القرار الذي أستخدمه:

• "هل يجب أن يحدث هذا في كل مرة بلا استثناء؟" -- هوك. تنسيق الكود، حظر الملفات المحمية، إرسال الإشعارات. لا غموض.
• "هل يحتاج Claude قدرة جديدة لا يملكها؟" -- خادم MCP. الوصول إلى قاعدة بيانات، استدعاء API، البحث في مستندات خارجية.
• "هل أريد تعليمات قابلة لإعادة الاستخدام لسير عمل محدد؟" -- Skill (أمر slash). قوالب مراجعة الكود، قوائم مراجعة النشر.
• "هل أريد تشكيل سلوك Claude في هذا المشروع؟" -- CLAUDE.md. معايير الترميز، قرارات المعمارية، المكتبات المفضلة.

أمثلة حقيقية توضح الحدود:

• "نسّق دائمًا مع Prettier" = هوك (يجب أن يحدث في كل مرة)
• "استخدم Prettier للتنسيق" في CLAUDE.md = توجيه (قد ينساه Claude)
• "ابحث في مستندات شركتنا" = MCP (قدرة جديدة)
• "اتبع دليل أسلوبنا عند مراجعة الكود" = Skill أو CLAUDE.md

كما هو موضح في إعلان Anthropic عن الإضافات، الهوكس جزء من نظام إضافات أشمل يضم أيضًا MCP وSkills. تم تصميمها لتكمل بعضها، لا لتتنافس.

حزمة البداية: إعداد هوكس Claude Code الجاهز لأي مشروع

يجب أن يشمل إعداد الهوكس الأساسي لـClaude Code: التنسيق التلقائي عند تحرير الملفات، والإشعار عند اكتمال المهمة، وحماية الملفات الحساسة، وإدخال سياق الجلسة، وهوك Stop للتنظيف. هذا بالضبط هو الإعداد الذي أضعه في كل مشروع جديد -- معدَّل للمكدس التقني، لكن البنية تبقى كما هي.

الإعداد

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Project: '\"$(basename $(pwd))\"' | Branch: '\"$(git branch --show-current 2>/dev/null)\"' | Node: '\"$(node -v 2>/dev/null)\"'\"}'; exit 0"
      }]
    }],
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "if": "tool_input.file_path matches '(\\.env|\\.env\\..+|.*lock\\.json|.*lock\\.yaml)'",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"message\": \"Protected file. Edit manually.\"}' && exit 2"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "FILE=$(jq -r '.tool_input.file_path // .tool_input.file' /dev/stdin); case \"$FILE\" in *.ts|*.tsx|*.js|*.jsx) npx prettier --write \"$FILE\" 2>/dev/null;; *.py) black \"$FILE\" 2>/dev/null;; *.go) gofmt -w \"$FILE\" 2>/dev/null;; esac; exit 0"
      }]
    }],
    "Notification": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "MSG=$(jq -r '.message // \"Done\"' /dev/stdin); osascript -e \"display notification \\\"$MSG\\\" with title \\\"Claude Code\\\"\" 2>/dev/null || notify-send 'Claude Code' \"$MSG\" 2>/dev/null; exit 0"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "echo '[STOP] '\"$(date +%H:%M:%S)\"'' >> .claude/session.log; exit 0"
      }]
    }]
  }
}

كيف تخصّصه لمكدسك التقني

استبدل أوامر التنسيق والاختبار في الإعداد أعلاه لتتناسب مع مكدسك. البنية تبقى متطابقة.

التحقق من عمل الهوكس

ثلاث طرق لتأكيد أن الهوكس نشطة:

1. أمر /hooks -- اكتب /hooks في Claude Code لرؤية جميع الهوكس المسجّلة ومُطابقاتها وحالتها.
2. فحص نسخة الجلسة -- بعد إطلاق هوك، تحقق من نسخة الجلسة. تظهر تنفيذات الهوكس مع مخرجاتها ورمز الخروج.
3. التبديل السريع -- أضف "disableAllHooks": true إلى settings.json لتعطيل جميع الهوكس مؤقتًا دون حذف الإعداد. أزله (أو اضبطه على false) لإعادة التفعيل.

تكامل CI/CD: هوكس Claude Code في الوضع Headless

تعمل هوكس Claude Code في الوضع headless (claude -p) مع بعض الاختلافات: لا تزال هوكس Notification تُطلَق لكن يجب إعادة توجيهها إلى التسجيل بدلًا من تنبيهات سطح المكتب. يمكن لهوكس PreToolUse برمز الخروج 2 إيقاف جلسات headless مؤقتًا لمراجعة بشرية. يستخدم GitHub Actions الإجراء anthropics/claude-code-action@v1 إلى جانب الهوكس لسير عمل آلي.

سلوك الوضع Headless

المفاجأة الكبرى في الوضع headless: هوكس PreToolUse التي تخرج برمز 2 لا تفشل بصمت. بل تُوقف الجلسة مؤقتًا وتتيح لك الاستئناف بـ--resume، مما يمنحك نمط "الإنسان في الحلقة" لمسارات CI/CD.

تكامل GitHub Actions

إليك سير عمل GitHub Actions بسيط يستخدم Claude Code مع الهوكس. كما هو موثّق في دليل GitHub Actions الرسمي:

- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    prompt: "Review this PR and suggest improvements"
    allowed_tools: "Read,Grep,Glob"
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

هوكس .claude/settings.json تسافر مع المستودع، لذا ستُطلَق في CI تمامًا كما تفعل محليًا. فقط تأكد من أن أي هوكس تعتمد على أدوات خاصة بسطح المكتب (مثل osascript) لديها بدائل أو شروط.

إدارة الهوكس للفرق

نمط يعمل جيدًا مع الفرق:

• .claude/settings.json (محفوظ في Git) -- الهوكس المشتركة بالفريق: حماية الملفات، المُنسّقات، حماية الفروع. يحصل عليها الجميع.
• .claude/settings.local.json (في .gitignore) -- الهوكس الشخصية: تفضيلات الإشعارات، التسجيل المخصص، الهوكس التجريبية.
• ~/.claude/settings.json (عام على مستوى المستخدم) -- إعداداتك الافتراضية عبر جميع المشاريع: أسلوب الإشعارات، تفضيلات التنسيق الشخصية.

هذا يعكس كيفية عمل .editorconfig (محفوظ) وإعدادات IDE المحلية (شخصية). كما أشار دليل Angelo Lima لـCI/CD، الفرق التي توحّد الهوكس المشتركة ترى مشاكل أقل من نوع "يعمل على جهازي" مع Claude Code.

استكشاف أخطاء هوكس Claude Code وإصلاحها والأخطاء الشائعة

تشمل المشاكل الشائعة في هوكس Claude Code: الهوكس لا تُطلَق (تحقق من تهجئة المُطابق وموقع settings.json)، والهوكس تُشغَّل لكن لا تحظر (رمز خروج خاطئ -- استخدم 2 لا 1)، والحلقات اللانهائية (هوك Stop تُطلق نفسها)، والبطء عند بدء التشغيل (عدد كبير جدًا من الهوكس المتزامنة). الخطأ الأكثر شيوعًا الذي أراه هو الارتباك في رمز الخروج -- يستخدم المطورون exit 1 بينما يقصدون exit 2.

الهوك لا تُطلَق

الأعراض: أضفت هوكًا لكن لا شيء يحدث عند وقوع الحدث.

الحلول:

• خطأ مطبعي في المُطابق -- المُطابقات حساسة لحالة الأحرف. "write" لن تُطابق أداة Write. تحقق من أسماء الأدوات الدقيقة بـ/hooks.
• ملف إعداد خاطئ -- هوكس في ~/.claude/settings.json لن تظهر في مخرجات /hooks لنطاق المشروع. جرّب .claude/settings.json في جذر المشروع.
• خطأ في صياغة JSON -- فاصلة زائدة أو قوس ناقص يُعطّل إعداد الهوكس بأكمله بصمت. شغّل settings.json عبر jq . للتحقق منه.
• disableAllHooks: true -- تحقق إذا كان شخص ما (أو جلسة تصحيح سابقة) تركت هذه العلامة مفعّلة.

الهوك تُشغَّل لكن لا تحظر

الأعراض: هوك PreToolUse تُنفَّذ، لكن الإجراء يتابع رغم ذلك.

الحلول:

• رمز خروج خاطئ -- رمز الخروج 1 يعني "خطأ" (فشلت الهوك)، لا "حظر". استخدم exit 2 لحظر إجراء. هذا يُربك الجميع تقريبًا، كما أشارت الوثائق الرسمية.
• غياب JSON في stdout -- للهوكس الحاظرة، أخرج رسالة JSON حتى يعرف Claude سبب الحظر: echo '{"message": "Blocked: reason"}'

الحلقات اللانهائية

الأعراض: يستمر Claude في إعادة محاولة نفس الإجراء، أو يسخن جهازك بشكل مريب.

الحلول:

• هوك Stop تُطلق إجراءات -- إذا كتبت هوك Stop ملفًا أو شغّلت أمرًا يجعل Claude يستجيب، فقد أنشأت حلقة. هوكس Stop يجب أن تقوم فقط بأشياء سلبية: تسجيل، إشعار، تنظيف.
• هوك PostToolUse تُسبب تعديلات -- هوك PostToolUse تعدّل ملفًا تُطلق حدث PostToolUse آخر. احمِ من ذلك بمُطابقات محددة أو حقل if.

مشاكل الأداء

الأعراض: يستغرق Claude وقتًا أطول بشكل ملحوظ للبدء أو تنفيذ الأدوات.

الحلول:

• عدد كبير جدًا من هوكس SessionStart -- كل واحدة تُشغَّل بشكل متزامن عند بدء التشغيل. أبقِها خفيفة (أقل من ثانية واحدة لكل منها).
• نصوص ثقيلة في المسارات الساخنة -- هوكس PreToolUse وPostToolUse تُطلَق كثيرًا. إذا كان نصك يُجري طلبات شبكة أو حسابات ثقيلة، أضف حقل timeout (بالميللي ثانية) وفكّر هل يجب أن تكون هوك HTTP بدلًا.
• بلا تخزين مؤقت -- إذا كنت تتحقق من نفس الشيء بشكل متكرر (مثل "هل هذا فرع محمي؟")، خزّن النتيجة في ملف مؤقت بدلًا من تشغيل أوامر Git على كل استدعاء هوك.

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

ما هي هوكس Claude Code وكيف تعمل؟

هوكس Claude Code هي نصوص أتمتة معرّفة من قِبَل المستخدم تُنفَّذ عند أحداث دورة حياة محددة خلال جلسة Claude Code. تُعدّها في settings.json بنمط مُطابق ومُعالج (أمر shell، نقطة نهاية HTTP، مطالبة، أو وكيل). عندما يُطلَق الحدث المطابق، تُشغَّل الهوك تلقائيًا وتستخدم رموز الخروج للتحكم في النتيجة.

كيف أُعدّ الهوكس في settings.json الخاص بـClaude Code؟

أضف كائن "hooks" إلى أي من مواقع الإعداد الثلاثة: ~/.claude/settings.json (عام على مستوى المستخدم)، .claude/settings.json (مشترك بالمشروع)، أو .claude/settings.local.json (شخصي للمشروع). يُربط كل نوع حدث بمصفوفة من تعريفات الهوكس التي تحتوي على matcher، وحقل if اختياري، ومصفوفة hooks تحتوي كائنات المُعالج مع type وcommand أو url.

ما الفرق بين هوكس PreToolUse وPostToolUse؟

تُطلَق PreToolUse قبل تنفيذ أداة، مما يمنحك القدرة على حظرها برمز الخروج 2. تُطلَق PostToolUse بعد اكتمال التنفيذ، مفيدة للتنسيق والاختبار والتسجيل. PreToolUse للوقاية والتحكم البوابي. PostToolUse للتحقق والتنظيف. كلاهما يستقبل اسم الأداة ومدخلاتها كـJSON عبر stdin.

هل يمكن لهوكس Claude Code حظر الأوامر الخطرة؟

نعم. هوكس PreToolUse برمز الخروج 2 تحظر أي تنفيذ للأداة. يمكنك حماية الملفات الحساسة من الكتابة، وحظر أوامر shell المطابقة لأنماط خطرة مثل rm -rf أو git push main، ومنع الوصول إلى قواعد بيانات الإنتاج. رسالة الحظر تُرسَل إلى Claude كتغذية راجعة، حتى يتمكن من تعديل نهجه.

ما أحداث الهوك المتاحة في Claude Code؟

يوفر Claude Code 15+ حدثًا: PreToolUse وPostToolUse لتنفيذ الأدوات، وNotification للتنبيهات، وStop لنهاية الجلسة، وSessionStart للتهيئة، وUserPromptSubmit لتصفية المدخلات، وPreCompact وPostCompact لإدارة السياق، وأحداث أحدث مثل ConfigChange وFileChanged وTaskCreated وPermissionDenied. راجع جدول المرجع الكامل في قسم أحداث الهوك أعلاه.

كيف تختلف الهوكس عن أدوات MCP وSkills؟

الهوكس حتمية -- تُطلَق دائمًا على الأحداث المطابقة بغض النظر عما يقرره Claude. أدوات MCP توسّع قدرات Claude (الوصول إلى قواعد البيانات، استدعاءات API) لكن Claude يختار متى يستخدمها. Skills هي حزم تعليمات قابلة لإعادة الاستخدام تُستدعى بأوامر slash. CLAUDE.md يوفر توجيهًا سلوكيًا. استخدم الهوكس عندما يجب أن يحدث شيء ما في كل مرة، وMCP عندما يحتاج Claude قدرات جديدة.

هل تعمل هوكس Claude Code في الوضع Headless؟

نعم، مع بعض التحفظات. تُطلَق الهوكس بشكل طبيعي في الوضع headless (claude -p)، لكن الهوكس الخاصة بسطح المكتب مثل إشعارات macOS تحتاج بدائل. بشكل مهم، هوكس PreToolUse التي تخرج برمز 2 يمكنها إيقاف جلسات headless مؤقتًا للموافقة البشرية عبر --resume. هذا يُتيح أنماط "الإنسان في الحلقة" لمسارات CI/CD حيث تتطلب إجراءات معينة موافقة يدوية.

كم هوك كثير؟ هل تُبطّئ الهوكس Claude Code؟

لا يوجد حد صارم، لكن كل هوك متزامنة تُضيف زمن استجابة. تُشغَّل هوكس SessionStart عند بدء التشغيل، لذا أبقِها سريعة (أقل من ثانية واحدة لكل منها). هوكس PreToolUse وPostToolUse تُطلَق على كل استدعاء أداة مطابق -- النصوص الثقيلة هنا تتراكم بسرعة. أنصح بإبقاء إجمالي الهوكس أقل من 10-15، واستخدام حقل if لتضييق النطاق، وإضافة قيم timeout لمنع النصوص الجامحة.

هل يمكنني استخدام الهوكس للتنسيق التلقائي مع Prettier أو Black؟

نعم -- إنها حالة الاستخدام الأكثر شيوعًا للهوكس. أنشئ هوك PostToolUse تُطابق Write|Edit، استخرج مسار الملف من JSON في stdin، وشغّل المُنسّق المناسب حسب امتداد الملف. راجع المثال رقم واحد في قسم الأمثلة العملية للحصول على إعداد كامل جاهز للنسخ واللصق يتعامل مع ملفات TypeScript وJavaScript وPython.

هل هوكس Claude Code آمنة؟ ما هي مخاطر الأمان؟

تُشغَّل الهوكس بصلاحياتك الكاملة كمستخدم -- لا يوجد صندوق رمل. يمكن لهوك خبيثة قراءة مفاتيح SSH، وحذف الملفات، أو تسريب البيانات. استخدم فقط هوكس من مصادر موثوقة، راجع أي .claude/settings.json مشترك قبل قبوله في مشروعك، واستخدم .claude/settings.local.json للهوكس الشخصية التي لا ينبغي مشاركتها. لأنماط أمان الذكاء الاصطناعي الأشمل، راجع دليل حواجز اللغة الكبيرة LLM.