ثمانية خطافات تضمن موثوقية وكيل الذكاء الاصطناعي

ملف CLAUDE.md مجرد اقتراح. إذا كتبت “شغّل Prettier قبل الـ commit”، سيتجاهل الوكيل هذا التعليم مرة من كل ثلاث تقريباً. صياغة التعليمات بدقة أكبر لا تحل المشكلة. معدل الامتثال البالغ 80% ليس مشكلة في جودة النموذج، بل قيد هيكلي ينشأ من وضع القواعد داخل نافذة السياق والأمل في أن النموذج يلتزم بها.

الخطافات تعمل على مستوى مختلف تماماً. هي سكريبتات تُنفَّذ تلقائياً عند نقاط محددة في دورة الحياة، بصرف النظر عما يقرره النموذج. PreToolUse يُطلق قبل أن يعدّل الوكيل ملفاً أو يشغّل أمراً. PostToolUse يُطلق بعده مباشرة. النموذج لا يختار تشغيلها أو تجاهلها، فهي تعمل وكفى.

الفارق العملي واضح فوراً. إضافة عشرة أسطر من القواعد إلى CLAUDE.md شيء، وإضافة خطاف واحد إلى .claude/settings.json شيء آخر تماماً. رمز الخروج 2 يوقف عمل الوكيل في مكانه. رمز الخروج 0 يسمح له بالمتابعة. أي رمز آخر يسجّل تحذيراً دون إيقاف. ولأن الخطافات تعيش في settings.json، تلتزم بها بمجرد عملية commit واحدة ويحصل عليها الفريق بالكامل عبر git.

الحراس الأربعة قبل التنفيذ

أشغّل الخطافات منذ أكثر من ستة أشهر. هذه الأربعة خطافات من نوع PreToolUse نجت في كل مشروع دون أن تُحذف مرة واحدة.

حجب الأوامر الخطيرة يرصد الأنماط المدمرة كـrm -rf وgit reset --hard وDROP TABLE عبر تطابق تعبيرات منتظمة، ثم يعيد رمز الخروج 2 لوقف العملية قبل حدوثها. رأيت وكلاء يحاولون تنفيذ rm -rf على مجلدات لا ينبغي لهم لمسها. بدون هذا الخطاف، كان الضرر سيكون حقيقياً.

حماية الملفات الحساسة يحجب أي محاولة تعديل على .env وpackage-lock.json و*.pem وما شابهها. الوكيل لن يحصل على فرصة الكتابة فوق ملف القفل أو تسريب بيانات الاعتماد داخل commit.

اشتراط اجتياز الاختبارات قبل طلب المراجعة يربط إنشاء pull request بنجاح الاختبارات. اضبط المطابق على mcp__github__create_pull_request ولن يستطيع الوكيل حرفياً فتح طلب مراجعة حتى تجتاز الاختبارات. لن تسمع “سأصلح الاختبارات لاحقاً” بعد الآن.

تسجيل كل أمر يكتب كل أمر bash يشغّله الوكيل في .claude/command-log.txt مع الطوابع الزمنية. بعد ثلاثة أيام حين يبدو شيء ما خاطئاً، يمكنك تتبع ما حدث بالضبط.

المفتشون الثلاثة بعد التنفيذ

خطافات PostToolUse تعمل فور انتهاء الوكيل من تعديل ملف. أسلسل ثلاثة منها بالتتابع.

التنسيق التلقائي يشغّل Prettier على كل ملف مُعدَّل. لمشاريع Python استبدله بـBlack، ولـGo استخدم gofmt. المنسّق يعمل سواء تذكّر الوكيل التنسيق أم لا.

الفحص التلقائي يشغّل ESLint مباشرة بعد التنسيق. إذا اكتشف ESLint أخطاء، يراها الوكيل في الحال ويصلحها في نفس الجولة. عدد مشكلات الـlint التي تصل إلى مراجعة الكود البشرية يقترب من الصفر.

الاختبار التلقائي يشغّل مجموعة الاختبارات المرتبطة بعد كل تعديل على الملف. حين يفشل اختبار، يعلم الوكيل بذلك في ثوانٍ ويحاول الإصلاح. أمرر المخرجات عبر tail -5 للاحتفاظ بالملخص فقط، مما يمنع مخرجات الاختبار من إغراق نافذة السياق.

الترتيب مهم. Prettier أولاً، ثم ESLint، ثم الاختبارات. بحلول الوقت الذي ينظر فيه إنسان إلى الكود، يكون التنسيق والفحص قد اجتازا بالفعل. تعليقات الأسلوب في مراجعة الكود تختفي.

حفظ العمل حين يتوقف الوكيل

خطاف Stop واحد يتولى هذه المهمة: الـcommit التلقائي يشغّل git add -A && git commit في كل مرة ينهي فيها الوكيل رده. كل وحدة عمل تحصل على commit مستقل. لن تختلط مهمتان في commit واحد أبداً.

ادمج هذا مع git worktrees وستحصل على commits تلقائية على فروع الميزات. إذا تعطّل الوكيل أو قاطعته، لن تفقد آخر جزء من العمل.

ما لم يعمل بسلاسة

تسلسل الخطافات يبدو أنيقاً على الورق، لكن تشخيص سلسلة فاشلة أصعب من تشخيص سكريبت واحد. حين بدأ خطاف الاختبار التلقائي يفشل بصمت لأن مشغّل الاختبار لم يكن مثبتاً في مشروع جديد، أمضيت ساعة أتتبع سبب إنتاج الوكيل لكود غير مختبر. الخطاف كان يعيد رمز الخروج 0 لأن السكريبت نفسه لم يُعثر عليه، والـshell عامل “command not found” كحالة غير حاجبة. اضطررت لإضافة فحص صريح لوجود مشغّل الاختبار قبل استدعائه.

الأداء قيد آخر. القلق الشائع هو أن الخطافات الكثيرة تُبطئ الأمور، لكن هذا ليس الوصف الدقيق. السؤال الحقيقي هو ما إذا كان كل خطاف منفرد ينتهي في أقل من 200 مللي ثانية. تشغيل Prettier على ملف واحد يأخذ نحو 50ms. فحص ESLint نحو 80ms. الاختبارات تتفاوت، لكن تضييق النطاق على الملفات المتأثرة يُبقي معظم التشغيلات سريعة. إذا أخذ أي خطاف منفرد أكثر من ثانية، بدأت حلقة تغذية راجعة الوكيل تبدو بطيئة.

الصورة الأشمل

مقالة هندسة الـHarness لـOpenAI أشارت إلى أن الوكلاء يعملون بأفضل حالاتهم داخل حدود صارمة وهيكل متوقع. فلسفة تصميم React تقول الشيء ذاته عن المكوّنات: وحدات قابلة للتركيب بمراحل دورة حياة محددة وحالة واضحة.

الخطافات في Claude Code تتبع نفس المبدأ. الحالة تقابل الجلسات والذاكرة. الخطافات هي الدوال التي تتدخل عند حدود دورة الحياة. PreToolUse يرسم الحدود. PostToolUse يجعل الهيكل متوقعاً. Stop يحفظ النتيجة.

السطر الذي كنت أضعه في CLAUDE.md لتشغيل Prettier اختفى. الخطاف يشغّله في كل مرة، دون أن يُطلب منه ذلك.