تنفّذ Hooks في Claude Code أمرًا ثابتًا في لحظة محددة: قبل أن يشغّل Claude أداة، أو بعد أن يعدّل ملفًا، أو حين ينهي ردّه. فبدل أن تذكّره كل جلسة بتنسيق الكود أو بعدم لمس ملف الأسرار، تتولى الوصفة ذلك كل مرة. وهي لـ Claude Code وحده، لا لمحادثات claude.ai.
33 وصفة مرتبة حسب لحظة تشغيلها
كل وصفة ملف Markdown يحدد الحدث (event) والمطابِق (matcher) والمتطلبات، ثم السكربت. يذكر وصف الحزمة الأصلي 28 وصفة، والمجلد المرفق يضم 33: سبع قبل تنفيذ الأداة (PreToolUse)، و17 بعدها (PostToolUse)، وسبع عند انتهاء Claude (Stop)، وواحدة للتنبيهات، وواحدة عند بدء الجلسة. أبرزها:
- file-protection: يرفض تعديل .env وpackage-lock.json وما داخل .git وnode_modules، ويخرج بالرمز 2، فيُمنع التعديل ويعرف Claude السبب.
- sql-bulk-delete-warn: ينبّه قبل DELETE أو UPDATE بلا WHERE أو TRUNCATE TABLE عبر psql أو mysql أو sqlite3 أو sqlcmd، ويمنع الأمر إذا ضبطت CC_SQL_BULK_DELETE_BLOCK=1.
- file-backup: ينسخ الملف قبل تعديله إلى .claude/backups مع طابع زمني.
- smart-formatting: يختار المنسّق من امتداد الملف: prettier لـ JS وTS وJSON وCSS وMarkdown، وblack لبايثون، وgofmt لـ Go.
- test-runner: يشغّل ملف الاختبار المعدَّل وحده عبر npm test أو pytest.
- إشعارات Slack وDiscord وTelegram: تسع وصفات، لكل منصة رسالة حين ينهي Claude ردّه، وأخرى بوقت الانتهاء، وثالثة لتنبيهات Claude Code في Slack، ولأخطاء Bash في Discord وTelegram.
- windows-python-stub-detector: يكشف عند بدء الجلسة بديل python3 من Microsoft Store في Git Bash على ويندوز، الذي يوقف وصفات بايثون بصمت.
مثال: رسالة commit خارج الصيغة
تعمل conventional-commits قبل أداة Bash. إذا كتب Claude الأمر git commit -m “update stuff”، يوقفه السكربت بالرمز 2 لأن سطر العنوان لا يبدأ بنوع مثل feat أو fix، ويعيد إلى Claude الصيغة المطلوبة <type>[optional scope][!]: <description>، فيصححها Claude ويعيد المحاولة. تغيّر قائمة الأنواع بالمتغير CC_TYPES وتوقف الفحص بـ CC_SKIP=1، ولأنه يسبق تنفيذ الأمر لا يتجاوزه الخيار --no-verify.
التركيب وصفة بعد وصفة
- افتح plugin/hooks واختر وصفة، وانسخ كتلة Script منها إلى ملف مثل .claude/hooks/conventional-commits.sh.
- في .claude/settings.json، تحت المفتاح hooks، أضف الحدث والمطابِق المذكورين في رأس الوصفة، وأمرًا من النوع command مثل bash “$CLAUDE_PROJECT_DIR/.claude/hooks/conventional-commits.sh”، ثم تأكد منه بالأمر /hooks. التفاصيل في توثيق Hooks الرسمي.
- وصفات Slack وDiscord وTelegram تحتاج SLACK_WEBHOOK_URL أو DISCORD_WEBHOOK_URL أو TELEGRAM_BOT_TOKEN مع TELEGRAM_CHAT_ID، وبدونها تخرج دون إرسال.
لا يحوي المجلد ملف hooks.json، فنسخه كإضافة لا يفعّل شيئًا. نقلتُ الوصفات دون تعديل، وأرفقتُ دليلًا عربيًا وفهرسًا بأسماء الملفات.
قبل التفعيل
- السكربتات مكتوبة بـ bash ومعظمها يحتاج jq، وعلى ويندوز يشغّلها Claude Code عبر Git Bash. وإشعارات سطح المكتب تعتمد osascript على macOS وnotify-send على لينكس.
- file-protection وfile-protection-hook شبه متطابقتين، وauto-git-add وgit-add-changes وsmart-commit كلها تضيف الملف المعدَّل إلى staging، وsmart-commit لا ينشئ commit رغم اسمه. فعّل واحدة من كل مجموعة.
- مطابِق بعض وصفات التنسيق والاختبار هو Edit وحده، فلا تعمل على ما تكتبه أداة Write ما لم توسّعه.
- ثلاث وصفات تقرأ حقولًا لا يذكرها توثيق Claude Code الحالي، فعدّلها قبل الاعتماد عليها: no-vibes، التي تعترض إعلان «done» بلا دليل تحقق، تقرأ closing_message وtranscript بدل last_assistant_message، ووصفتا الأخطاء في Discord وTelegram تقرآن tool_result بدل tool_response.
الترخيص MIT، والحقوق لمجتمع BuildWithClaude، ولمشروع cc-safe-setup في وصفتي sql-bulk-delete-warn وwindows-python-stub-detector، ولمشروع llm-dark-patterns (Apache-2.0) في وصفة no-vibes.
