تناول مقالنا الأول عن منهجية RPI سؤال "لماذا": وكلاء البرمجة يقدّمون أفضل ما عندهم حين تُقسَّم المهمة إلى بحث (Research) وتخطيط (Plan) وتنفيذ (Implement)، ويبقى سياق كل مرحلة نظيفًا. هذا المقال عن "كيف". إنه الإعداد الذي نعمل به يوميًا مع الوكلاء الفرعيين (subagents) في Claude Code، بما في ذلك الأجزاء التي لم تسر كما أردنا.
لا شيء هنا مقياس أداء. هذا فريق صغير يدير مستودعًا واحدًا (monorepo) يضم نحو اثني عشر منتجًا (نظام دعم فني، ونظام MES، واستضافة بريد، ومساعد ذكاء اصطناعي لجامعة)، ويتولى وكيل برمجة بالذكاء الاصطناعي جزءًا كبيرًا من العمل. قصص الإخفاق هي الجزء المفيد.
باختصار
- البحث يجري في وكيل فرعي، ولا يجري أبدًا في المحادثة الرئيسية. يعيد ملخصًا أو يكتب ملفًا.
- التخطيط يحدث في المحادثة الرئيسية، مكتوبًا، قبل أي تغيير في الكود.
- التنفيذ يجري في وكيل فرعي واحد أو أكثر، لكل منها نطاق ضيق وملكية واضحة للملفات والأدوات.
- التحقق يكون مقابل شيء لا يمكن أن يكذب عليك: ملف على القرص، أو تحميل جديد للصفحة، أو مقارنة طول. ولا يكون أبدًا مقابل ما يرويه الوكيل عن نفسه.
لماذا مكان البحث هو الوكيل الفرعي
البحث هو المرحلة التي تستهلك السياق. قراءة السجلات، والبحث في الكود بـ grep، وسحب تصدير من Search Console، وتقليب صندوق بريد: معظم هذه المخرجات يُنظر إليها مرة واحدة ولا يُحتاج إليها بعد ذلك. إن وصلت إلى المحادثة الرئيسية فستبقى فيها في كل دور لاحق، وتدفع النموذج خارج ما يسميه Dex Horthy "المنطقة الذكية" إلى "المنطقة الغبية"، حيث يبدأ بنسيان التعليمات وتكرار الأخطاء.
تذكر وثائق Anthropic عن الوكلاء الفرعيين الهدف بوضوح: "حافظ على السياق بإبقاء الاستكشاف والتنفيذ خارج محادثتك الرئيسية". يحصل كل وكيل فرعي على نافذة سياق خاصة به ولا يعيد إلا ملخصًا.
عمليًا، يختلف وكلاء البحث عندنا عن السؤال السريع في أمرين:
- يكتبون نتائجهم في ملف. حين بحثنا عن موضوعات لهذه المدونة، كتب وكيل البحث ملف موضوعات منظمًا بالمصادر وعبارات البحث المستهدفة، وأعاد ملخصًا من 200 كلمة. والكتّاب الذين جاؤوا بعده قرؤوا الملف، لا الملخص.
- يُقال لهم ما لا يفعلونه. عبارة "بحث فقط، بلا نشر، بلا متصفح" جزء من التوجيه. وكيل البحث الذي يبدأ بإصلاح الأشياء في منتصف التحقيق هو الطريق إلى تغييرات لم يخطط لها أحد.
مثال على أهمية مرحلة البحث: أشار Search Console إلى 79 صفحة في موقعنا على أنها "صفحة بديلة لها علامة canonical صحيحة". الخطوة السهلة كانت البدء بتعديل علامات canonical. لكن فحص أمثلة الروابط أولًا أظهر أن أيًّا منها لم يكن على موقعنا أصلًا. كانت تابعة لنطاق فرعي منسي يشير إلى خادم لا نديره. الإصلاح كان حذف سجل DNS واحد، دون لمس أي قالب. البحث أولًا وفّر علينا تغييرًا بلا معنى في الكود.
التخطيط: المرحلة الوحيدة التي تبقى في المحادثة الرئيسية
الخطة هي المكان الذي يدخل فيه حكمك أنت، لذلك تبقى حيث تراها. خططنا قصيرة ومحددة: أي الملفات تتغير، وكيف يبدو "الانتهاء"، وما الخارج عن النطاق صراحةً، وكيف ستُفحص النتيجة.
أنفع عادة اكتسبناها هي كتابة توجيه كل وكيل فرعي كأنه لزميل كفء دخل الغرفة للتو: ماذا يفعل، وما الذي لا يلمسه، وماذا يقدّم في تقريره وبكم كلمة. التوجيهات من نوع "أصلح الخلل بناءً على ما وجدته" تلقي عبء التفكير على الوكيل الفرعي، والنتائج تُظهر ذلك. أما التوجيهات التي تسمّي الملف والدالة وطريقة الفحص فتعود صحيحة في أغلب الأحيان.
التنفيذ: الوكلاء المتوازيون يحتاجون قواعد ملكية
تشغيل عدة وكلاء تنفيذ في وقت واحد هو مصدر توفير الوقت، وهو أيضًا المكان الذي وقعت فيه معظم حوادثنا. خرجنا منها بثلاث قواعد.
1. لكل مورد مشترك وكيل واحد يملكه
نقود متصفحًا حقيقيًا عبر منفذ تصحيح عن بُعد للمهام التي لا تملك واجهة برمجية: Reddit، ومحادثة Telegram، وواجهة Search Console. وكيلان يقودان المتصفح نفسه في آن واحد يعني تبويبات تتبدل من تحت كل منهما وإجراءات تقع على الصفحة الخطأ. لذلك صار كل توجيه ينص على ذلك: "أنت الوكيل الوحيد المسموح له بقيادة المتصفح"، أو "بلا متصفح، وكيل آخر يملكه". والأمر نفسه ينطبق على صندوق بريد، أو ترحيل قاعدة بيانات، أو عملية نشر.
وتعلّمنا أيضًا أن "المتصفح" ليس دائمًا شيئًا واحدًا. في إحدى المرات كانت أداة المتصفح التي يستخدمها الوكيل متصلة بنسخة متصفح أخرى معزولة، غير تلك الموجودة على منفذ التصحيح. كان موقع ما يحظرها بينما لم يكن يحظر المتصفح الحقيقي. فحص قائمة الأهداف مباشرة (curl localhost:9222/json) والاتصال بها صراحةً حلّ المشكلة.
2. اعمل commit بسرعة، ولا تثق أبدًا بشجرة عمل غير محفوظة
حين تتشارك عدة جلسات مستودعًا واحدًا، يصبح العمل غير المحفوظ في commit هشًّا. فقدنا تعديلات مرة حين نفّذت جلسة أخرى git reset --hard في شجرة العمل نفسها. القاعدة منذ ذلك الحين: commits صغيرة تُدفع فورًا، وgit add بمسار صريح حتى لا يجرف أي وكيل تغييرات غير مكتملة لغيره.
ظهرت المشكلة المعاكسة هذا الشهر. كان موقعنا الإنتاجي يُبنى من شجرة عمل تحتوي ملفات لم يحفظها أحد في commit قط. الكود المتتبَّع كان يستوردها، فكان الموقع يُبنى بلا مشاكل على ذلك الجهاز وحده. وحين انتقل الموقع إلى خادم جديد، فشل البناء من نسخة نظيفة من main. الإصلاح كان حفظ الملفات الناقصة وإثبات ذلك ببناء من شجرة عمل جديدة. "يُبنى هنا" ليست مثل "يُبنى".
3. حدّد نطاق كل وكيل بأصغر شيء يمكن فحصه
"حدّث عناوين SEO" توجيه فضفاض. أما "غيّر meta_title وmeta_description فقط في هذه المستندات الثلاثة، واحفظ كل حقل آخر كما هو، ثم اطلب الصفحة الحية بـ curl وتأكد من العنوان الجديد" فهو نوع المهمة التي ينهيها الوكيل بشكل صحيح. حين سمحنا مرة لوكيل بتحديث مستندات كاملة، أسقط الترجمات العربية في الطريق، وكان التوجيه الأضيق سيمنع ذلك.
التحقق: افحص الواقع لا سجل المحادثة
هذا هو الدرس الأغلى ثمنًا. حين يقول الوكيل "انتهيت" فهذا يعني أنه يعتقد أنه انتهى. وحتى مخرجات الأدوات المعروضة على النموذج ليست دائمًا الحقيقة. والحذر نفسه ينطبق على خوادم MCP التي يستدعيها الوكيل: كل منها يعمل بالصلاحيات التي تمنحه إياها، ولهذا انتهى بنا الأمر إلى تدقيق إعداد MCP لدينا بعد حملة Deadbugz.
مخرجات الأدوات قد تكون خاطئة بصمت
في الجلسات الطويلة رأينا نتائج أدوات معروضة سقطت منها كلمات دون أي إشارة. البيانات الأصلية كانت سليمة، أما النص الذي رآه النموذج فلم يكن كذلك. كاد ذلك يقودنا مرتين إلى استنتاج خاطئ، منها تشخيص خاطئ بأن موقعًا ما يُفسد مدخلات النماذج. الإصلاح ممل: اكتب النتائج في ملف واقرأ الملف، أو قارن الطول أو المجموع الاختباري (checksum) بدل التدقيق في النص بالعين. وقبل أن ننشر أي منشور عبر نموذج ويب الآن، يتأكد الوكيل من أن عدد أحرف الحقل يطابق المصدر تمامًا.
"ضُغط الزر" لا تعني "أُرسلت الرسالة"
أسوأ حوادثنا كانت في محادثة Telegram على الويب مع جهة عمل حقيقية. أدخل الوكيل النص في مربع الرسالة بأمر تعديل على DOM. ظهر النص على الشاشة، لكن حالة المسودة الداخلية في التطبيق لم تتحدث. كل محاولة إرسال قرأت حالة قديمة وناقصة، وأرسلت المحاولات المتكررة سبعة مقاطع مشوهة إلى الطرف الآخر قبل أن ينتبه أحد. حذفناها عبر الواجهة البرمجية للتطبيق نفسه وأرسلنا رسالة واحدة سليمة.
خرج من ذلك تغييران. صار الإدخال يمر عبر أحداث إدخال حقيقية يستمع إليها التطبيق فعلًا. وبعد الإرسال، يقرأ الوكيل الرسالة من مخزن بيانات التطبيق نفسه ويقارنها بالنص المقصود قبل أن يعلن النجاح. علامة الصح الخضراء في الواجهة ليست دليلًا.
تحقّق من حيث يقف المستخدم
بعد النشر، افحص الرابط الحي من الخارج، لا الحاوية التي أعدت تشغيلها للتو. نشرنا إصلاحًا لـ SEO، وتأكدنا منه على خادمنا، ثم لاحظنا لاحقًا أن DNS الخاص بالنطاق صار يشير إلى خادم آخر ما زال يقدّم النسخة القديمة. فحص الأمرين معًا، بـ curl --resolve للخادم الأصلي وبطلب عادي لما يراه الجمهور، كان سيكشف ذلك فورًا.
قالب توجيه يعمل عندنا
Task: one sentence.
Scope: the exact files, records or pages. What is out of scope.
Ownership: which shared resources you may use (browser, mailbox, deploy).
Rules: no bypassing bot checks, no paid actions, commit by path only.
Verify: the specific check that proves it worked.
Report: under N words, with commit hashes and anything that needs a human.يبدو ذلك عبئًا إضافيًا. عمليًا هو الفرق بين محاولة واحدة وثلاث.
فحص عمل الوكيل هو أيضًا مشكلة الثقة التي تعطّل معظم مشاريع الوكلاء في المؤسسات؛ اقرأ لماذا لا يعمل في الإنتاج سوى 11% من وكلاء الذكاء الاصطناعي المعتمدة.
ما نقوله لفريق يبدأ مع RPI والوكلاء الفرعيين
- ابدأ بنقل البحث إلى وكلاء فرعيين. هذا أرخص مكسب وأقل مخاطرة.
- أبقِ الخطة في المحادثة الرئيسية، وأبقها مكتوبة.
- لا تضف التنفيذ المتوازي إلا حين تكون لديك قواعد ملكية للموارد المشتركة.
- اجعل كل وكيل يثبت نتيجته مقابل النظام الفعلي. ثق بالملف، وبتحميل الصفحة من جديد، وبالمجموع الاختباري، لا بالملخص.
لفهم المنطق وراء المراحل الثلاث، راجع الجزء الأول. ولنظرة أوسع على هذا المجال، يُعد الدليل العملي لهندسة السياق من Sourcegraph قراءة مكمّلة جيدة.
ساعد الذكاء الاصطناعي في صياغة هذا المقال؛ أما سير العمل والحوادث والإصلاحات فهي من تجربتنا.
