حين يعدّل Claude Code ملفًا في مشروعك، لا يظهر أن التعديل كسر اختبارًا إلا عندما تشغّل الاختبارات بنفسك، وربما بعد تعديلات كثيرة يصعب معها تتبّع السبب. تجمع هذه الحزمة وصفتَي إعداد تصفان ربط تشغيل الاختبارات بحدث PostToolUse، حتى يعمل أمر الاختبار تلقائيًا بعد كل استدعاء لأداة Edit، وكتبتُ هنا كيف تنفّذ هذا الربط بنفسك. الـ Hooks ميزة في Claude Code وحده، فلا أثر لهذا الإعداد في المحادثات العادية على claude.ai.
الوصفتان داخل plugin/hooks
- run-tests-after-changes: تشغيل اختبارات سريعة بعد كل تعديل للتأكد من أن شيئًا لم ينكسر. تناسب مشروعًا لديه مجموعة اختبارات قصيرة تشغّلها كاملة في كل مرة.
- test-runner: تشغيل الاختبارات المرتبطة بالتعديل وحدها. تناسب مشروعًا يطول فيه تشغيل كل الاختبارات، فتختار منها ما يخص الملف الذي تغيّر.
تتفق الوصفتان في الإعداد: الحدث PostToolUse، والمطابِق Edit، واللغة المعلنة bash، وتنص كل منهما على أنها لا تحتاج متغيرات بيئة ولا متطلبات. ويعرّف ملف plugin/.claude-plugin/plugin.json الحزمة باسم hooks-testing والإصدار 1.0.0.
من الوصفة إلى Hook يعمل
خذ وصفة run-tests-after-changes مثالًا. تطبيقها يعني أن تضيف في ملف الإعدادات، تحت مفتاح hooks، إدخالًا لحدث PostToolUse مطابقه Edit، وداخله Hook من نوع command يستدعي أمر الاختبار السريع في مشروعك، مثل pytest -x -q أو npm test. بعدها يشغّل Claude Code هذا الأمر كلما عدّل ملفًا بأداة Edit. وإذا أردت أن يقرأ Claude الفشل ويصلحه، فاجعل السكربت يكتب مخرجات الاختبار الفاشل إلى stderr وينتهي برمز الخروج 2؛ ففي حدث PostToolUse يعرض هذا الرمز على Claude ما كُتب في stderr بحسب توثيق Hooks الرسمي.
أما test-runner فيحتاج خطوة زائدة تكتبها أنت: سكربت يقرأ مسار الملف المعدَّل من الحقل tool_input.file_path في بيانات JSON التي يمررها Claude Code إلى الـ Hook عبر الإدخال القياسي، ثم يشغّل ملف الاختبار المقابل له وحده.
التثبيت في مشروعك
- فك ضغط الملف، وافتح plugin/hooks، واختر الوصفة التي تناسب حجم اختباراتك.
- شغّل أمر الاختبار من الطرفية أولًا، وتأكد أنه ينجح وينتهي بسرعة.
- افتح الملف .claude/settings.json في جذر المشروع ليقتصر الإعداد عليه، أو ~/.claude/settings.json ليشمل مشاريعك كلها.
- أضف إدخال PostToolUse بالمطابِق Edit وأمر الاختبار. وإن أردت أن يشمل الملفات الجديدة التي ينشئها Claude فاكتب المطابِق Edit|Write.
- احفظ الملف، ثم اطلب من Claude تعديلًا صغيرًا وتحقق من تنفيذ الأمر؛ ويعرض لك الأمر /hooks ما سجّلته.
ما تحتاجه وما لا تجده في الملفين
- Claude Code مثبت ومسجّل الدخول، ومشروع فيه اختبارات تعمل من الطرفية، ومفسّر bash على جهازك لأن الوصفتين تعلنانه لغةً للأمر.
- الوصفتان تصفان الحدث والمطابِق والغرض، ولا تحتويان سطر الأمر نفسه ولا ملف hooks.json؛ لذلك لا يتفعّل شيء بمجرد نسخهما، وأمر الاختبار تكتبه أنت بحسب أداة الاختبار في مشروعك.
- الأمر يعمل بعد كل تعديل، فالاختبارات البطيئة تبطئ الجلسة كلها؛ ابدأ بأسرع مجموعة لديك.
- المطابِق يتبع اسم الأداة لا الملف، فإذا غيّر Claude ملفًا بأمر في الطرفية بدل أداة Edit لم يعمل الـ Hook.
- الـ Hook ينفّذ أوامر على جهازك بصلاحيات حسابك، فراجع الأمر قبل حفظه.
ما أرفقتُه مع الملفات الأصلية
أرفقتُ دليلًا عربيًا في README-AR.md بخطوات البدء، وفهرسًا للمكونات في COMPONENTS.md، وملف PROVENANCE.json الذي يسجّل المستودع ورقم الـ commit الذي نُسخت منه الملفات. الترخيص MIT، وحقوق الوصفتين لـ davepoon ومجتمع BuildWithClaude في مستودع buildwithclaude، ونص الترخيص في licenses/1-LICENSE.
