حاول وكيل كنت أشرف عليه ذات مرة تنفيذ git reset --hard origin/main على فرع يحتوي على ساعتين من العمل غير المُرحَّل. كان قد قرر أن شجرة العمل "فوضوية" ويريد بداية جديدة نظيفة. السبب الوحيد الذي جعلني أحتفظ بذلك العمل هو hook من نوع PreToolUse يحظر أي git reset --hard.
هذا هو المبرر الكامل لـ Claude Code hooks. إنها الفرق بين "النموذج يتصرف بشكل صحيح في الغالب" و"النموذج حرفيًا لا يستطيع فعل ذلك الشيء." الـ Prompts هي اقتراحات. الـ Hooks هي القانون، لأن الإطار التشغيلي ينفذها، وليس النموذج.
لماذا يتفوق الـ hook دائمًا على الـ prompt
يمكنك كتابة "لا تُشغّل أبدًا أوامر git المدمرة" في prompt النظام بأحرف كبيرة وثلاثة علامات تعجب. على Opus 4.8 يعمل ذلك في معظم الأحيان — فهو يتبع التعليمات بدقة. لكن "في معظم الأحيان" هو المشكلة. سلوك النموذج هو توزيع احتمالي. أما الـ hook فهو شرط منطقي. عندما يكون الحد الأمني مهمًا فعلًا — حذف البيانات، والدفع إلى الإنتاج، وإرسال بريد إلكتروني — فأنت تريد الشرط المنطقي، لا التوزيع الاحتمالي.
ثمة سبب أعمق يتعلق بكيفية استدلال هذه النماذج على الأدوات. يصدر النموذج استدعاءً لأداة؛ ويقرر إطارك التشغيلي ماذا يفعل به. أداة bash تسلّم الإطار التشغيلي سلسلة أمر معتمة. الـ hook هو المكان الذي تكسر فيه تلك السلسلة وتتخذ قرارًا حتميًا: سماح، أو حظر، أو استفسار. لا تدخل نية النموذج في الحسبان أبدًا.
الـ hooks الثلاثة التي أستخدمها فعلًا
PreToolUse — الحارس. يُطلق قبل تنفيذ الأداة. يحصل على اسم الأداة والإدخال. أعد قرار حظر ولن تحدث الاستدعاء أبدًا. هنا يعيش حارس git reset --hard الخاص بي، إضافة إلى حظر rm -rf خارج مجلد مؤقت وأي curl يُوجَّه إلى shell.
# PreToolUse: رفض git المدمر على أداة bash
if echo "$TOOL_INPUT" | grep -qE 'git reset --hard|git clean -[a-z]*f|git push --force'; then
echo '{"decision":"block","reason":"Destructive git blocked. Stash or commit, then ask me."}'
exit 0
fi
الـ reason مهم. يعود إلى النموذج، لذا بدلًا من التخبط يقرأ الوكيل "احفظ مؤقتًا أو ارحّل، ثم اسألني" ويفعل ذلك. الحظر الصامت يجعل الوكيل يعيد المحاولة بصياغات مختلفة حتى يجد صياغة أفلتت من تعبيرك النمطي. أخبره لماذا.
PostToolUse — المفتش. يُطلق بعد تشغيل الأداة. أستخدمه لإجراء فحص lint سريع أو التحقق من الأنواع بعد كل تعديل على الملفات، وإعادة تغذية الإخفاقات مباشرةً. يحصل الوكيل على خطأ النوع بعد ثانيتين من كتابة الخطأ بدلًا من اكتشافه بعد ثلاث مهام فرعية حين لا يُترجم شيء. إحكام حلقة التغذية الراجعة تلك أسهم في تحسين جودة كود وكلائي أكثر من أي تغيير في الـ prompt.
Stop — مفتاح الإيقاف. يُطلق حين يظن الوكيل أنه انتهى. هذه فرصتك الأخيرة لتقول "لا، لم ينته بعد." أتحقق من أن الاختبارات تنجح فعلًا قبل السماح للتشغيل بالانتهاء. إن لم تنجح، يحظر hook الـ Stop التوقف ويأمر الوكيل بإصلاحها. هنا أيضًا يعيش عداد اكتشاف الحلقة المذكور سابقًا — تعديلات كثيرة جدًا، أوقف كل شيء.
أين تعيش الـ hooks
تُهيَّأ الـ hooks في settings.json، وليس في ذاكرة النموذج أو في CLAUDE.md الخاص بك. هذا ما يُربك الناس باستمرار. "من الآن فصاعدًا، شغّل دائمًا الـ linter بعد التحرير" ليس شيئًا تخبره للنموذج — سينساه بحلول الدور الثلاثين. إنه hook PostToolUse يُشغّله الإطار التشغيلي في كل مرة. السلوك الآلي المتكرر ينتمي إلى settings.json. التفضيلات تنتمي إلى الذاكرة. لا تخلط بينهما.
هيكل سريع بلا تكلف:
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{"type": "command", "command": "~/.claude/guards/git-guard.sh"}]
}]
}
}
يحدد الـ matcher نطاق الـ hook لأداة بعينها. حدد النطاق بإحكام. Hook من نوع PreToolUse يُطلق على كل أداة ويحلل كل إدخال ويستدعي shell يضيف كمونًا إلى التشغيل بأكمله. تعلمت ذلك بالطريقة الصعبة حين أضاف سكريبت حارس باستدعاء شبكة غير ضروري ثانية كاملة لكل استدعاء bash في جلسة من 300 استدعاء.
الخطأ الذي يرتكبه الجميع
القوائم السوداء. غريزتك الأولى هي إدراج الأوامر السيئة في قائمة سوداء. rm -rf، git reset، DROP TABLE. النموذج أكثر إبداعًا من قائمتك السوداء. سيجد find . -delete، أو يشفر الأمر بـ base64، أو يستخدم أداة نسيت أمرها.
اعتمد بدلًا من ذلك قائمة بيضاء للعمليات الآمنة كلما أمكن. لوكيل بحث للقراءة فقط، اسمح بـ grep وglob وread وweb_search واحظر كل شيء آخر افتراضيًا. إعداده أكثر إزعاجًا. لكنه أيضًا النسخة الوحيدة التي تصمد حين يصبح النموذج ذكيًا. القائمة السوداء تحميك من الإخفاقات التي تخيلتها. القائمة البيضاء تحميك من تلك التي لم تتخيلها.
الوكلاء الذين يعملون دون إشراف في إعدادي يشتركون في سمة واحدة: أثق في الـ hooks، لا في النموذج. النموذج ذكي وسريع ويقرر أحيانًا أن ساعتيك من العمل تبدوان فوضويتين. الـ hook بسيط ولا يغير رأيه أبدًا. عندما يكون شيء لا يمكن التراجع عنه على المحك، البساطة وعدم تغيير الرأي هما بالضبط ما تريد.
اكتب الحارس قبل أن تسمح لأي أحد بالدخول إلى النادي.