الـhooks التي تستحق التشغيل في مستودع موقع
الوكيل الذي يعدّل مستودعك يحتاج بوابات لا قراءة أدقّ. أحداث الـhooks الثلاثة التي تسدّد ثمنها في موقع، ورمز الخروج الذي يجعل البوابة بوابة.
الوكيل القادر على تعديل مستودعك سيعدّله خطأً في مرحلة ما. ليس كثيراً، ونادراً بشكل يبدو خاطئاً في الـdiff، لكن بما يكفي ليجعل قراءة كل تغيير بنفسك تُفرغ فكرة الوكيل من معناها. الحل ليس قراءة أدق، بل بوابة: سكربت يعمل وحده في نقطة ثابتة من الجلسة ويرفض التغيير عند فشله. يسمّيها Claude Code hooks، وفي مستودع موقع ثلاثة منها تؤدي معظم العمل.
الـhook أمر صدفة له رأي
الـhook أمر يشغّله Claude Code في نقطة مسمّاة من الجلسة، ويصل إلى stdin ملف JSON يصف ما حدث للتو. يقرأ سكربتك ذلك الـJSON، يقرّر، ثم يجيب عبر رمز الخروج. الخروج بصفر يعني لا رأي، فيمضي الإجراء في مسار الأذونات المعتاد. الخروج باثنين يحجب الإجراء، وما كتبه السكربت إلى stderr يصبح السبب الذي يراه Claude. وما عدا ذلك خطأ غير حاجب. هذه تقريباً كل الواجهة، ودليل البداية يغطّي الباقي.
هذا أهم مما يبدو. البوابة التي تحذّر فقط ليست بوابة، لأن وكيلاً يعمل على مهمة طويلة سيقرأ التحذير ويقرّ به ثم يكمل. البوابة التي تخرج باثنين تُسقط الخيار. والانضباط هو أن تحدّد، لكل فحص يهمّك، أتريد إيقاف العمل فعلاً أم مجرّد التعليق عليه، ثم تختار رمز الخروج المطابق.
الأحداث الثلاثة التي تستحق مكانها في موقع
يعدّ مرجع الـhooks عشرات الأحداث، وهو أمر مُربك حتى تلاحظ أنها تنقسم إلى ثلاث وتائر: مرة لكل جلسة، ومرة لكل دور، ومرة لكل نداء أداة. ومستودع الموقع يحتاج واحداً من كل وتيرة.
| الحدث | الوتيرة | ما نُحكمه به |
|---|---|---|
| PreToolUse | قبل كل نداء أداة | تعديلات ملفات لا يجوز أن تتغيّر، والأسرار |
| PostToolUse | بعد نجاح نداء أداة | إخبار الوكيل بنتيجة لا يراها |
| Stop | عند انتهاء Claude من الرد | فحص الأنواع والبناء قبل أن تصدّق العمل |
البوابة الأولى: لا تدع البناء يتعطّل بصمت
أعلى الـhooks قيمة في مستودع موقع هو الذي يشغّل فحص الأنواع وبناء الإنتاج على حدث Stop، عند انتهاء Claude من الرد. إنه أرخص جواب ممكن للسؤال الذي يُنهي كل جلسة وكيل: هل هذا أخضر فعلاً؟ جلسة لمست أربعة عشر ملفاً وأعلنت النجاح ليست دليلاً. البناء الذي تَرجم هو الدليل.
في هذا الموقع البوابة أمر واحد، وقد أمسكت عيوباً حقيقية لم تمسكها قراءة الـdiff. تسعة مفاتيح أيقونات مُختلقة في دفعة واحدة من المقالات، لأن ملف البيانات يتحقّق منها وقت البناء ولا شيء قبله يفعل. ومدخل ناقص في جدول استدعاء كان سيُعطّل ثمانية وثمانين صفحة مدينة وقت الطلب. كلاهما كان سيصل الإنتاج بفضل ملخّص واثق. ولم ينجُ أيٌّ منهما من البناء. والمقال المرافق عن التحقق من عمل الوكيل يمرّ على بقية القائمة.
البوابة الثانية: احجب التعديل الذي لن توافق عليه أبداً
يُطلَق PreToolUse قبل نداء الأداة ويمكنه رفضه. النمط الموثّق هو matcher يضيّق إلى أداة، وشرط اختياري يضيّق أكثر، وسكربت يخرج باثنين مع سبب. وفي موقع، قائمة ما يستحقّ الرفض قصيرة وثابتة: الكتابة إلى ملف البيئة، والكتابة إلى أي شيء مُولَّد، وأي أمر يدفع قبل تشغيل البناء.
الإغراء أن تكتب هذا كقاعدة أذونات، وبعضه يجب أن يكون كذلك: قاعدة منع في ملف الإعدادات أبسط ولا تحتاج سكربتاً. استعمل الـhook حين يعتمد القرار على المحتوى لا على المسار، وهذه حال الأسرار تماماً. قاعدة المسار لا تخبرك أن النص المُزمَع كتابته في مكوّن هو مفتاح API حقيقي. أما hook يفحص المحتوى المقترح فيخبرك.
البوابة الثالثة: أخبر الوكيل بما لا يمكنه معرفته
أقلّ حقل مُستخدَماً في المنظومة كلها هو additionalContext على PostToolUse. يأخذ نصاً، ويلفّه كملاحظة، ويضعه بجانب نتيجة الأداة فيقرأه Claude في الطلب التالي. ليس حجباً، بل تصحيحاً يُسلَّم في اللحظة الوحيدة التي ما زال الوكيل ممسكاً فيها بالفكرة المعنيّة.
يُطلَق عندنا عند الكتابة في ملف تحت مجلّد الصور، ويقول شيئاً واحداً: المُحسِّن يُخزّن بحسب مسار المصدر لا بحسب المحتوى، فالاستبدال في المكان يخدم الملف القديم حتى يُفرَّغ مجلّد الكاش. هذا سلوك موثّق في تحسين الصور في Next.js، وهو غير مرئي من الـdiff، ولا من البناء، ولا من لقطة شاشة أُخذت مبكّراً. كلّفنا جولتَي ارتباك قبل وجود الـhook، ولم يكلّفنا شيئاً بعده.
لكل مستودع ثلاث أو أربع حقائق من هذا النوع: صحيحة، ذات أثر، وغير مستنتجة من الكود. موضعها hook لا تعليمات المشروع، لأن ملاحظة تُطلَق عند التعديل المعنيّ تصل أفضل من سطر في ملف قرأه الوكيل قبل أربعين دقيقة. والمقال عن كتابة CLAUDE.md يغيّر القرارات يبيّن أين يقع الحدّ بين الاثنين.
الـhooks ليست تكاملاً مستمراً
يعمل الـhook على جهازك، في جلستك، تحت إعداداتك. يحمي العمل الجاري، لا الفرع، لأن زميلاً بلا ملف إعداداتك لا يناله شيء منه، وكذلك أي شيء يصل المستودع بطريق آخر. ولذلك ما زلت تريد سير عمل في التكامل المستمر يشغّل الأوامر نفسها على نسخة نظيفة.
الطريقة النافعة لفهم الاثنين أن الـhook بوابة محليّة سريعة مضبوطة لحلقة الوكيل، والتكامل المستمر بوابة مرجعية بطيئة مضبوطة للفرع. شغّل السكربت نفسه في كليهما ليكون للأخضر تعريف واحد. وعند اختلافهما، الـhook هو المخطئ.
ابدأ بواحد
ثلاث بوابات هي المنتهى لا المبتدأ. أضف hook الـStop الذي يشغّل بناءك، واعمل به أسبوعاً، وانظر ما يبقى يمرّ. أما الـhook الثاني والثالث فيجب أن يُكتبا ضدّ عيوب وقعت لك فعلاً، لأن بوابة تحرس فشلاً لا يحدث ضريبةٌ على كل جلسة بلا مقابل. وفي موقع كموقعنا كان الترتيب بيّناً بعد حين: بوابة البناء سدّدت ثمنها في اليوم الأول، وملاحظة كاش الصور في الأسبوع الأول، وبوابة الأسرار لم تُطلَق قطّ، وهذا هو المقدار الصحيح لها.
إن لم تكن قد هيّأت المستودع بعد، فـدليل البناء هو نقطة البداية، ومقال المهارات يغطّي النصف الآخر من الإعداد. نفعل هذا في عمل العملاء كجزء من بناء مخصّص، وتُسلَّم البوابات مع التسليم.
