ما هي Claude Code Hooks وكيفية استخدامها؟

لمطوري Vibe Coders، تعمل أدوات مثل Claude Code من Anthropic على تغيير طريقة كتابة المطورين لأكوادهم وتصحيحها وإدارة مشاريعهم. يعمل Claude Code كـ "أداة ترميز وكيلة" تعيش في جهازك الطرفي (الترمينال)، قادرة على فهم قاعدة التعليمات البرمجية بأكملها، والتفاعل مع نظام الملفات الخاص بك، وتشغيل الأوامر، وحتى تصفح الويب للحصول على التوثيق. إنه يتفوق في مهام مثل كتابة ميزات جديدة، وإصلاح الأخطاء، وإعادة هيكلة التعليمات البرمجية من خلال مطالبات اللغة الطبيعية.

ومع ذلك، فإن السمة الأساسية لنماذج اللغة الكبيرة (LLMs) هي طبيعتها الاحتمالية. بينما يسمح هذا بحل المشكلات بشكل إبداعي، إلا أنه قد يؤدي أحيانًا إلى عدم القدرة على التنبؤ. قد ترغب في أن تحدث بعض الإجراءات—مثل فحص ملف بعد تغييره أو تشغيل الاختبارات بعد كتابة دالة جديدة—*في كل مرة* دون فشل. الاعتماد على نموذج اللغة الكبير لتذكر القيام بذلك في كل حالة يمكن أن يكون غير متسق.

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

يقدم هذا المقال دليلاً شاملاً لفهم وتكوين والاستفادة من Claude Code Hooks لإنشاء سير عمل تطوير مؤتمت بالكامل ومبسط.

ما هي Claude Code Hooks؟

في جوهرها، Claude Code Hooks هي أوامر shell يحددها المستخدم ويتم تنفيذها تلقائيًا في نقاط محددة من دورة حياة Claude Code. تعمل هذه الخطافات كمحفزات يمكنك تكوينها لتشغيلها قبل أو بعد إجراءات معينة، مما يتيح لك إدخال منطقك المخصص ونصوصك البرمجية وأوامرك مباشرة في عمليات Claude.

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

هناك أربعة أحداث رئيسية في دورة الحياة يمكن أن تؤدي إلى تشغيل الخطاف:

1. PreToolUse: يتم التنفيذ قبل أن يستخدم Claude أداة معينة (على سبيل المثال، قبل الكتابة إلى ملف).
2. PostToolUse: يتم التنفيذ بعد استخدام أداة بنجاح (على سبيل المثال، بعد تعديل ملف).
3. Notification: يتم التنفيذ كلما أرسل Claude إشعارًا (على سبيل المثال، عندما يحتاج إلى إدخال المستخدم أو أكمل مهمة طويلة).
4. Stop: يتم التنفيذ عندما ينتهي Claude من إنشاء استجابته ويتوقف.

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

تشريح Claude Code Hooks: نظرة عميقة على التكوين

لاستخدام الخطافات، تحتاج إلى تعريفها في ملف إعدادات Claude Code الخاص بك. يتم ذلك عن طريق إضافة جدول [[hooks]] إلى ملف settings.toml الخاص بك، والذي يقع في دليل .claude/ داخل مشروعك. يحتوي كل تكوين خطاف على بعض المكونات الرئيسية.

# Example Hook in .claude/settings.toml

[[hooks]]
# The event that triggers the hook.
event = "PostToolUse" 

# (Optional) Conditions for the hook to run.
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# The shell command to execute.
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (Optional) Whether to run the command in the background.
run_in_background = false 

دعنا نفصل كل جزء بالتفصيل.

حقل event في Claude Code Hooks (مطلوب)

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

• "PreToolUse"
• "PostToolUse"
• "Notification"
• "Stop"

حقل hooks.matcher في Claude Code Hooks (اختياري)

المطابق (matcher) هو ما يسمح لك بتحديد *متى* يجب تشغيل الخطاف بدقة. إذا حذفت المطابق، فسيتم تشغيل الخطاف لكل مثيل من الحدث المحدد. على سبيل المثال، سيتم تشغيل خطاف PostToolUse بدون مطابق بعد *كل* استدعاء أداة.

يحتوي المطابق على ثلاثة حقول يمكنك استخدامها لتصفية الأحداث:

• tool_name: سلسلة تطابق اسم الأداة المستخدمة. هذا مثالي لاستهداف إجراءات محددة مثل edit_file أو git_commit أو run_command.
• file_paths: مصفوفة من السلاسل تحتوي على أنماط glob. سيتم تشغيل الخطاف فقط إذا كانت الملفات المتضمنة في استخدام الأداة تطابق أحد هذه الأنماط. على سبيل المثال، ["*.py"] يستهدف جميع ملفات بايثون، بينما ["src/components/**/*.jsx"] يستهدف ملفات JSX في دليل معين.
• query: سلسلة تطابق الإدخال المعطى لأداة. هذا مفيد للمحفزات الأكثر تحديدًا، مثل تشغيل خطاف فقط عندما يتم استخدام أداة run_command مع أمر يتضمن npm.

حقل command لـ Claude Code Hooks (مطلوب)

هذا هو جوهر الخطاف—أمر الـ shell الذي سيتم تنفيذه عند استيفاء شروط التشغيل. يتم تشغيل هذا الأمر بنفس صلاحيات حساب المستخدم الخاص بك، لذا يمكنه فعل أي شيء يمكنك فعله في جهازك الطرفي (الترمينال).

لجعل الأوامر ديناميكية، يوفر Claude Code مجموعة من متغيرات البيئة التي يتم ملؤها بالسياق من الحدث الذي أدى إلى تشغيل الخطاف.

متغيرات البيئة المتاحة:

• $CLAUDE_EVENT_TYPE: نوع الحدث (PreToolUse، PostToolUse، إلخ).
• $CLAUDE_TOOL_NAME: اسم الأداة التي تم استخدامها (على سبيل المثال، edit_file).
• $CLAUDE_TOOL_INPUT: معلمات الإدخال الخام التي تم تمريرها إلى الأداة بتنسيق JSON.
• $CLAUDE_FILE_PATHS: قائمة بمسارات الملفات ذات الصلة باستدعاء الأداة مفصولة بمسافات. هذا مفيد بشكل لا يصدق لتمرير الملفات إلى أدوات التنسيق (formatters)، أو أدوات فحص الأكواد (linters)، أو مشغلات الاختبارات (test runners).
• $CLAUDE_NOTIFICATION: محتوى رسالة الإشعار (فقط لحدث Notification).
• $CLAUDE_TOOL_OUTPUT: المخرجات من تنفيذ الأداة (فقط لحدث PostToolUse).

إعداد run_in_background لـ Claude Code Hooks (اختياري)

هذه قيمة منطقية (`true` أو `false`). إذا تم تعيينها على `true`، فسيتم تنفيذ أمر الخطاف في عملية منفصلة، ولن ينتظر Claude اكتمالها قبل المتابعة. هذا مثالي للمهام طويلة الأمد مثل مجموعات الاختبار الشاملة أو عمليات البناء التي لا تريد أن تمنع الإجراءات اللاحقة لـ Claude. القيمة الافتراضية هي `false`.

حالات الاستخدام العملية والأمثلة لـ Claude Code Hooks

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

1. الفحص والتنسيق التلقائي باستخدام Claude Code Hooks

فرض نمط كود متناسق عبر مشروعك تلقائيًا. يقوم هذا الخطاف بتشغيل مدقق `ruff` ومنسق `black` على أي ملف بايثون يقوم Claude بتعديله.

الملف: .claude/settings.toml

[[hooks]]
event = "PostToolUse"

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py"]

# Command to lint, fix, and format the edited Python files.
command = "echo 'Running auto-formatter...' && ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

2. تشغيل الاختبارات تلقائيًا باستخدام Claude Code Hooks

من الممارسات الأساسية للتطوير القائم على الاختبار (TDD) هي كتابة الاختبارات ثم كتابة الكود لاجتياز تلك الاختبارات، والتكرار حتى يعمل كل شيء. يمكنك أتمتة خطوة "تشغيل الاختبارات" باستخدام خطاف. يقوم هذا المثال بتشغيل `pytest` كلما تم تعديل ملف في دليل `src/` أو `tests/`.

الملف: .claude/settings.toml

[[hooks]]
event = "PostToolUse"
run_in_background = true # Tests can be slow, run in background.

[hooks.matcher]
tool_name = "edit_file"
file_paths = ["src/**/*.py", "tests/**/*.py"]

# Command to run the test suite.
command = "pytest"

3. إشعارات سطح المكتب المخصصة عبر Claude Code Hooks

إذا طلبت من Claude أداء مهمة طويلة الأمد، فقد تبتعد عن جهاز الكمبيوتر الخاص بك. يستخدم هذا الخطاف أداة سطر أوامر مثل `ntfy` (خدمة إشعارات بسيطة قائمة على HTTP من نوع pub-sub) لإرسال إشعار فوري إلى هاتفك أو سطح مكتبك عندما يحتاج Claude إلى انتباهك.

الملف: .claude/settings.toml

[[hooks]]
event = "Notification"

# Sends the notification content to a public ntfy.sh topic.
# You can host your own for privacy.
command = 'ntfy publish my-claude-alerts "$CLAUDE_NOTIFICATION"'

4. فحوصات ما قبل الالتزام (Pre-Commit) باستخدام Claude Code Hooks

تمامًا مثل خطافات Git، يمكنك استخدام Claude Code Hooks لضمان الجودة *قبل* إجراء التزام (commit). يقوم هذا المثال بتشغيل نص برمجي مخصص للتحقق من مفاتيح API أو تنفيذ خطوات تحقق أخرى قبل السماح لـ Claude باستخدام أداة `git_commit`.

الملف: .claude/settings.toml

[[hooks]]
event = "PreToolUse"

[hooks.matcher]
tool_name = "git_commit"

# Command to run a pre-commit check script.
# The script should exit with a non-zero code to halt the commit.
command = "sh ./.claude/pre-commit-checks.sh"

إعداد وتصحيح أخطاء Claude Code Hooks الخاصة بك

البدء باستخدام الخطافات أمر بسيط، لكن التحقق وتصحيح الأخطاء هما مفتاح ضمان عملها كما هو متوقع.

1. إنشاء التكوين الخاص بك: تأكد من وجود ملف .claude/settings.toml في الدليل الجذر لمشروعك. أضف تكوينات [[hooks]] الخاصة بك هناك.
2. التحقق من التكوين: بعد حفظ ملف settings.toml الخاص بك، قم بتشغيل الأمر /hooks داخل واجهة طرفية Claude Code. سيعرض هذا الأمر الخاص تكوينات الخطافات المحملة حاليًا، مما يتيح لك رؤية ما إذا كان Claude قد قام بتحليلها بشكل صحيح على الفور.
3. التحقق من الأخطاء:

• TOML غير صالح: تأكد من أن ملف settings.toml الخاص بك يحتوي على بناء جملة صالح. يمكن أن يمنع قوس أو علامة اقتباس في غير مكانها من تحميله.
• مشاكل الأوامر: اختبر أمرك مباشرة في الـ shell الخاص بك للتأكد من أنه يعمل كما هو متوقع. تحقق من الأخطاء الإملائية وتأكد من أن الملفات التنفيذية الضرورية (black، pytest، ntfy، إلخ) موجودة في PATH نظامك.
• متغيرات تصحيح الأخطاء: لمعرفة القيم التي تحتوي عليها متغيرات البيئة، استخدم echo لكتابتها في ملف سجل. على سبيل المثال: command = "echo 'Tool: $CLAUDE_TOOL_NAME, Files: $CLAUDE_FILE_PATHS' >> /tmp/claude_hook.log"

الخلاصة: قوة Claude Code Hooks

ترفع Claude Code Hooks الأداة من مساعد ترميز عالي الكفاءة إلى شريك تطوير متكامل وحتمي. من خلال تحديد قواعد بسيطة وقوية، يمكنك أتمتة الأجزاء الروتينية ولكن الحاسمة من سير عملك، مما يحررك للتركيز على الجوانب المعقدة والإبداعية لهندسة البرمجيات. سواء كان الأمر يتعلق بفرض جودة الكود، أو تبسيط دورة TDD الخاصة بك، أو التكامل مع خدمات الطرف الثالث، توفر الخطافات الإطار القوي اللازم لتكييف Claude Code مع احتياجاتك الدقيقة.

كلما أصبحت أكثر دراية بقدرات Claude Code، ابدأ صغيرًا بخطاف تنسيق بسيط ثم استكشف أتمتة أكثر تعقيدًا. ستجد سريعًا أن هذه الميزة ضرورية لبناء بيئة تطوير مدعومة بالذكاء الاصطناعي يمكن التنبؤ بها، وفعالة، وشخصية حقًا.