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؟
ج لا. الخطافات تنفّذ تأثيرات جانبية فقط (نسخ احتياطي، تنسيق، إشعار)، ولا تغيّر المحتوى المُعاد.
س خطاف أم إضافة؟
ج الخطافات استجابات أحداث خفيفة (تنفيذ أوامر)؛ والإضافات توسيعات وظيفية كاملة (تسجيل أدوات، تعديل سلوك). احتياجات بسيطة: خطافات؛ واحتياجات معقدة: إضافات.
📖 ملخص
- الخطافات تُفعّل منطقاً مخصصاً في نقاط دورة حياة Claude Code الرئيسية
- الأحداث الأساسية: before/after:tool:write/read/bash
- النسخ الاحتياطي التلقائي والتدقيق الأمني والتنسيق التلقائي هي السيناريوهات الأكثر شيوعاً
- فشل خطاف before يمنع العمليات؛ وفشل خطاف after لا يمنعها
- أبقِ الخطافات سريعة (أقل من ثانية واحدة)
📝 تمارين
- أساسي (⭐): هيّئ خطاف after:tool:write يشغّل Prettier تلقائياً عند تعديل الملفات.
- متوسط (⭐⭐): هيّئ خطافات أمنية لمنع
rm -rfوnpm publish. - متقدم (⭐⭐⭐): صمّم حل خطافات كامل يغطي النسخ الاحتياطي والتنسيق والفحص الأمني والإشعارات.