كدتُ الثلاثاء الماضي أن أدفع API key إلى مستودع عام. Claude Code hook اعترضها قبل نصف ثانية من الـ commit. في تلك اللحظة تحوّلتُ من "الـ hooks مجرد ميزة إضافية" إلى "لن أُشغّل agent من دونها أبداً".
تُعدّ Claude Code hooks الميزة الأكثر استهانةً في هذه الأداة بأكملها، ولا يكاد أحد في قائمة متابعتي يستخدمها. دعني أُصلح ذلك. سأُريك بالضبط الـ hooks التي أُشغّلها في عملي المستقل، والإعدادات التي تُحرّكها، والـ hook الذي أنقذ مستودعي حقاً.
ما الـ hook في حقيقته
الـ hook هو أمر shell تُشغّله Claude Code تلقائياً عند وقوع حدث ما. قبل تشغيل أداة. بعد تعديل ملف. عند انتهاء الـ agent. لستَ تطلب من Claude أن يتذكّر فعل شيء ما — الـ harness هو من يفعله، بشكل حتمي، في كل مرة. هذا الفارق مهم. الـ agent الذي "يتذكر عادةً" تشغيل المُنسّق هو agent سيتناساه في أسوأ لحظة ممكنة.
تعيش الـ hooks في ملف settings.json. هذا هو شكلها:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "prettier --write \"$CLAUDE_FILE_PATHS\"" }
]
}
]
}
}
هذا يُشغّل Prettier على أي ملف يعدّله Claude، في اللحظة التي يعدّله فيها. لم أعد أفكر في التنسيق أبداً. الـ diff دائماً نظيف. لا مزيد من "آسف، 400 تغيير في المسافات" تُلوّث commits.
الـ hook الذي أنقذ مستودعي
هذا هو hook الـ API key. PreToolUse hook على Bash يفحص وجود git commit أو git push ويُجري grep على الـ diff المُقلَّد بحثاً عن أي شيء يشبه الأسرار.
{
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "~/.claude/scripts/secret-scan.sh" }
]
}
]
}
يُجري الـ script عملية grep على التغييرات المُقلَّدة بحثاً عن أنماط كـ sk- وAKIA وبعض بادئات مزوّديّ الخاصة. إذا أصاب، يخرج الـ script برمز غير صفري، والخروج غير الصفري من PreToolUse hook يحجب الإجراء. Claude حرفياً لا يستطيع تشغيل الأمر. يُخبَر بالسبب ويلتفّ حوله.
الثلاثاء الماضي أصاب. تركتُ agent يُعيد هيكلة ملف إعدادات فأدرج key مضمّناً من ملف env لم يكن يجب أن يقرأه. بدون الـ hook، كانت تلك الـ key ستظهر على GitHub، وكنتُ سأدور الـ credentials في منتصف الليل، وربما كان شخص ما يتعدّن على حسابي. مع الـ hook، حصلتُ على رسالة حجب من سطر واحد وتابعتُ. اثنا عشر سطراً من bash. أرخص تأمين أملكه.
الـ hooks اليومية
بعيداً عن الاثنين أعلاه، إليك ما يستحق حقاً مكانه.
PostToolUse hook يُشغّل مدقّق الأنواع بعد تعديلات على ملفات .ts ويُرجع الأخطاء مباشرةً إلى الـ agent. Claude يرى أخطاء الأنواع الخاصة به دون أن أنسخها وألصقها. يُصحّح نفسه في نفس الدور. حلقة التغذية الراجعة تلك وحدها تستحق الإعداد. الـ agent يُصلح الخطأ قبل أن أقرأه.
Stop hook يُطلق إشعار سطح المكتب عندما ينتهي Claude من مهمة طويلة. أُشغّل agents على إعادة هيكلة كبيرة وأذهب لتحضير الغداء. الإشعار يعني أنني لستُ أرقب المحطة الطرفية، أُلقي نظرة عليها كل تسعين ثانية مثل Tamagotchi.
{
"Stop": [
{ "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude is done\" with title \"CC\"'" }] }
]
}
بسيط للغاية. يُغيّر طريقة عملي بالكامل. أُطلق مهمة وأمضي بثقة حقيقية أنني سأُنبَّه.
الذي أزلتُه
جرّبتُ hook يُشغّل مجموعة الاختبارات الكاملة تلقائياً بعد كل تعديل. بدا مسؤولاً. كان مؤلماً. تستغرق المجموعة 40 ثانية، لذا كل تعديل صغير كان يتوقف لـ 40 ثانية، والـ agent يجلس خاملاً يُحرق بعد ظهيرتي. الدرس: الـ hooks يجب أن تكون سريعة أو غير متزامنة. الـ hook المتزامن البطيء يُحوّل agent الرشيق إلى دبس.
الآن الاختبارات تعمل فقط في Stop hook، مرة واحدة، في النهاية. الفحوصات السريعة (lint، أنواع، مسح الأسرار) تعمل بشكل مضمّن. الفحوصات البطيئة تعمل عند الحدود. طابق تكلفة الـ hook مع تكرار إطلاقه. إذا كان يُطلق عند كل تعديل، فمن الأفضل أن يعود في أقل من ثانية.
أين تضعها
الـ hooks الخاصة بالمشروع تذهب إلى .claude/settings.json في المستودع لتُشحن مع الكود ويحصل عليها زملائي. الشخصية، مثل إشعار سطح المكتب، تذهب إلى ~/.claude/settings.json لتتبعني عبر كل المشاريع. احتفظ بالماسح الضوئي للأسرار عاماً. تريده في كل مكان، بلا استثناءات، بلا "سأُضيفه لاحقاً".
تفصيلة كلّفتني ساعة: أوامر الـ hooks تعمل في shell غير تفاعلي. إذا كان أمرك يعتمد على شيء من .zshrc، لن يكون موجوداً. عرفتُ ذلك عندما كان prettier يعمل في طرفيتي ولا يفعل شيئاً صامتاً في الـ hook لأن الـ PATH كان مختلفاً. استخدم مسارات مطلقة أو npx.
ابدأ بواحدة
لا تبني كل هذا اليوم. أضف الماسح الضوئي للأسرار. هذه الواحدة فقط. إنها اثنا عشر سطراً وهي الفارق بين ثلاثاء هادئ وتمرين إطفاء حريق لتدوير الـ credentials.
ثم، حالما تثق بها، أضف المُنسّق. ثم الإشعار. في غضون أسبوع ستمتلك agent يُنسّق بنظافة، يحجب الأسرار، يُصحّح أخطاء أنواعه بنفسه، ويربت على كتفك عند الانتهاء — وستتوقف عن القيام بتلك الأشياء الأربعة يدوياً.
هذه هي الساعة يومياً. لم تكن مهمة واحدة كبيرة. كانت أربعين مهمة صغيرة، والآن script shell يؤدّيها بينما أُحضّر قهوتي.