حين يعمل Claude Code داخل مستودع Git يكتب رسائل commit بالصيغة التي يراها، وتبقى الملفات التي عدّلها خارج الـ staging حتى تضيفها بنفسك. هذه خمس وصفات Hooks تربط أوامر Git بأحداث أدوات Claude، وتعمل في Claude Code وحده، لا في محادثات claude.ai.
الوصفات الخمس، وما يصل منها بسكربته
PreToolUse يعمل قبل تنفيذ الأداة فيستطيع إيقافها، وPostToolUse يعمل بعدها.
- conventional-commits (PreToolUse، المطابِق Bash): يقرأ كل أمر git commit قبل تنفيذه، فإن لم تطابق رسالته صيغة type(scope): description، مثل feat: add login أو fix(api): handle null، أوقفه وأعاد إلى Claude سبب الرفض. المتغير CC_TYPES يستبدل الأنواع الافتراضية (feat وfix وdocs وغيرها)، وCC_SKIP=1 يعطّل الفحص.
- openspec-auto-archive (PreToolUse، Bash): قبل كل commit يبحث في openspec/changes عن التغييرات التي اكتملت خانات tasks.md فيها، فيؤرشفها بأمر openspec archive ويضيفها إلى الـ commit نفسه. وإن فشلت الأرشفة منع الـ commit وطلب من Claude تشغيل مهارة opsx:archive.
- auto-git-add (PostToolUse، Edit|MultiEdit|Write): يضيف الملف إلى الـ staging بأمر git add بعد كل تعديل أو إنشاء.
- git-add-changes (PostToolUse، Edit): الفكرة نفسها، بعد أداة Edit وحدها.
- smart-commit (PostToolUse، Edit): تصفه بطاقته بإنشاء commit برسالة مولّدة تلقائيًا.
نقلتُ الملفات كما هي. الوصفتان الأوليان تصلان بسكربتهما كاملًا، أما البطاقات الثلاث الأخيرة فتحدد الحدث والمطابِق والوصف دون سكربت. تجد سكربتاتها في مجموعة أمثلة Hooks، وهناك يتضح أن سكربت smart-commit يضيف الملف إلى الـ staging ويطبع مساره، ولا ينشئ commit ولا يكتب رسالة.
مثال: رسالة «updated login page»
إذا شغّل Claude git commit -m “updated login page”، فبحسب السكربت يقرأ الـ Hook الأمر من بيانات الحدث بأداة jq ويستخرج الرسالة التي تلي -m دون تنفيذه، ولأنها لا تطابق الصيغة يخرج بالرمز 2، فيُلغى الأمر ويصل إلى Claude نص فيه الرسالة المرفوضة والصيغة المطلوبة ومثال feat(parser): add ability to parse arrays، مع طلب إعادة كتابتها ثم المحاولة مجددًا. ولا يعترض على رسائل Merge وRevert وfixup!، ولا على commit يُكتب في المحرر أو يُقرأ من ملف بالخيار -F. ولأنه يعترض أداة Bash نفسها لا يتجاوزه الخيار --no-verify، بخلاف Hook الـ commit-msg في Git.
التركيب في Claude Code
- ثبّت jq، ومعه bash 3.2 أو أحدث وxargs. ووصفة OpenSpec تحتاج أداة openspec في PATH ومستودعًا فيه مجلد openspec/changes.
- انسخ كتلة Script من ملف الوصفة إلى ملف مثل .claude/hooks/conventional-commits.sh، واجعله قابلًا للتنفيذ. وأضف #!/usr/bin/env bash في أول سكربت conventional-commits، فكتلته تخلو منه.
- في .claude/settings.json داخل مشروعك، أو ~/.claude/settings.json لكل مشروعاتك، أضف تحت المفتاح hooks الحدث PreToolUse بالمطابِق Bash وأمرًا من النوع command يشير إلى الملف. ولوصفات الـ staging استخدم PostToolUse بمطابِق بطاقتها.
- اكتب /hooks لتتأكد أن الإعداد سُجّل.
أرفقتُ دليلًا عربيًا قصيرًا يحيل إلى توثيق Hooks الرسمي.
قبل التفعيل
- مجلد plugin بلا ملف hooks.json، فتثبيته كإضافة لا يفعّل شيئًا.
- دون jq تمرّر الوصفتان الكاملتان كل commit بلا فحص ولا تنبيه، ووصفة OpenSpec كذلك دون أداة openspec.
- auto-git-add وgit-add-changes وsmart-commit تؤدي بسكربتاتها المهمة نفسها، فاختر واحدة، وأيٌّ منها يضيف كل ملف يعدّله Claude، حتى ملف تجربة لا تريده في الـ commit.
- السكربتات مكتوبة لـ bash، فعلى ويندوز تلزمك بيئة مثل Git Bash.
الوصفات من مستودع buildwithclaude لـ davepoon ومجتمع BuildWithClaude، بترخيص MIT المرفق نصه في الحزمة.
