الوكلاء الفرعيون في Claude Code: عزل السياق والمنسّق والمراجع، ومتى لا تحتاجهم

ما هو الوكيل الفرعي في Claude Code

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

الكلمة المفتاحية هنا هي العزل. كل ما قرأه الوكيل الفرعي في الطريق — عشرات الملفات، ومخرجات اختبارات طويلة، وفرضيات لم تنجح — يبقى في سياقه ولا يدخل سياق الجلسة الرئيسية. ويرى الوكيل الرئيسي نتيجة قصيرة: «الخلل في الدالة X، والسبب كذا، وهذه ثلاثة مواضع متأثرة».

الوكلاء الفرعيون في Claude Code حالة خاصة من فكرة عامة هي أنظمة الوكلاء المتعددة: بدلاً من حلقة واحدة «فكّر ثم نفّذ ثم تحقق» يظهر رسم بياني من عدة عقد، لكل منها دور ومسؤولية.

لماذا يهم عزل السياق؟

نافذة السياق هي المورد الأهم للوكيل. تتسع فيها في الوقت نفسه تعليمات CLAUDE.md، وتاريخ الحوار، والشيفرة المقروءة، ومخرجات الأوامر. وحين يقضي الوكيل نصف ساعة في البحث عن سبب خلل، تمتلئ النافذة بملفات لا علاقة لها، وسجلات لا يهم منها إلا سطر واحد.

العواقب معروفة لكل من يعمل مع الوكلاء لفترة: يبدأ النموذج بحفظ قواعد المشروع بشكل أسوأ، ويخلط التفاصيل، وعند الضغط التلقائي للحوار يفقد ما كان مهماً. الوكيل الفرعي يحل هذه المشكلة بنيوياً: العمل القذر يُنجز في سياق منفصل يُتخلص منه بعد الرد.

• البحث والاستكشاف. «ابحث عن كل أماكن استدعاء دالة الدفع واشرح كيف تعمل» — مهمة نموذجية للوكيل الفرعي.
• الفحوص الصاخبة. تشغيل الاختبارات وتحليل ما فشل يُعهد به إلى وكيل فرعي، فيعود بقائمة الأسباب.
• قراءة الوثائق الكبيرة. مواصفة من مئات الصفحات تحتاج منها إلى بضع حقائق — ليستخرجها الوكيل الفرعي.

كيف تُعدّ وكيلاً فرعياً: مجلد .claude/agents

يُوصف الوكيل الفرعي الخاص بملف Markdown له ترويسة YAML. ملفات المشروع في .claude/agents/ داخل المستودع، فتصل إلى الفريق كله عبر git، والملفات الشخصية في ~/.claude/agents/ وتعمل في كل مشاريعك. ويمكن إنشاء الوكيل الفرعي وتعديله تفاعلياً بالأمر /agents في Claude Code.

---
name: code-reviewer
description: يراجع التغييرات في الشيفرة بحثاً عن الأخطاء ومخالفات قواعد المشروع. استخدمه بعد الانتهاء من المهمة وقبل الـ commit.
tools: Read, Grep, Glob, Bash
---
أنت مراجع شيفرة. لا يلزمك إصلاح أي شيء.

1. اطلع على التغييرات: git diff.
2. تحقّق من كل تغيير بحثاً عن أخطاء المنطق، ومعالجة الأخطاء،
   والأمان (SQL، وتهريب المخرجات، والأسرار).
3. قارن بالقواعد الواردة في AGENTS.md.
4. أعد قائمة الملاحظات: الملف، والسطر، والمشكلة، ولماذا هي مهمة.
   إذا لم توجد ملاحظات فقل ذلك صراحة.

معاني الحقول:

جسم الملف هو تعليمات النظام للوكيل الفرعي. ولا يرى تاريخ حوارك، لذلك ينبغي أن يكون كل ما يحتاجه عن دوره وصيغة رده موجوداً في التعليمات أو في المهمة التي يمررها الوكيل الرئيسي.

كيف تستدعي الوكيل الفرعي

قد يختار الوكيل الرئيسي الوكيل الفرعي بنفسه إذا كانت المهمة تناسب description. لكن الأضمن أن تطلب ذلك صراحة: «استخدم الوكيل الفرعي code-reviewer لمراجعة التغييرات». عبارات مثل «استخدمه بشكل استباقي» في الوصف ترفع احتمال استدعائه دون تذكير، لكنها لا تضمن ذلك.

الوكيل الفرعي المستكشف

الملف الثاني الذي يستحق إنشاءه تقريباً في أي مشروع هو مستكشف للقراءة فقط. يجيب عن أسئلة حول الشيفرة ولا يغيّر شيئاً.

---
name: explorer
description: يبحث في قاعدة الشيفرة عن إجابات حول مكان الأشياء وكيفية عملها. استخدمه حين تحتاج إلى قراءة ملفات كثيرة لاستخلاص إجابة قصيرة.
tools: Read, Grep, Glob
---
أنت تستكشف الشيفرة ولا تغيّر شيئاً.
أعد: إجابة مختصرة عن السؤال، وقائمة الملفات مع أرقام الأسطر التي تستند إليها،
وما الذي تعذّر التحقق منه.

هذا الوكيل مفيد بشكل خاص في بداية المهمة: يحصل الوكيل الرئيسي على خريطة للمواضع المطلوبة دون أن ينفق سياقه على قراءة كل شيء، ثم يعمل بعد ذلك مع ملفات محددة.

نمط «المنسّق والمنفذون»

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

1. يقسّم المنسّق المهمة إلى أجزاء مستقلة، ولكل جزء يكتب تكليفاً مكتملاً بذاته: الهدف، وأين يُبحث، ومتى يُعد الأمر منجزاً، وبأي شكل يُعاد الرد.
2. ينفّذ المنفذون التكليفات في سياقاتهم الخاصة.
3. يجمع المنسّق الردود، ويتحقق من أن الأجزاء تتلاءم، ويشغّل الخطوة التالية أو يعود إلى الخطوة السابقة.

نقطة الضعف في هذا النمط هي نقل المهمة. الوكيل الفرعي لا يعرف إلا ما كُتب له. التكليف «أصلح الخلل الذي ناقشناه» فارغ بالنسبة إليه، فهو لم يرَ النقاش. التكليف الجيد يُقرأ كمهمة لزميل جديد فتح المستودع للتو.

ما الذي يجب أن يعيده المنفذ؟

حدّد شكل الرد مسبقاً: قائمة الملفات، والمخرجات، والأسباب التي وُجدت، وما الذي لم يُتحقق منه. الرد القصير المنظم يوفر سياق المنسّق، والبند «ما الذي لم يُفحص» يحمي من الثقة الزائفة، فالمنفذ كأي وكيل يميل إلى الإبلاغ عن النجاح.

المراجع المنفصل: لماذا تفصل الحَكَم عن المنفذ؟

حين يكتب الوكيل نفسه الشيفرة ويفحصها بنفسه، يتشارك الحَكَم والمتهم رأساً واحداً. يتذكر الوكيل ما أراد فعله، ويرى في الشيفرة قصده لا ما هو مكتوب فعلاً. ثم إنه مهتم بإنهاء العمل، فيتحول الفحص إلى شكليات.

المراجع في سياق منفصل ينجو من هذه المشكلات. لا يعرف تاريخ القرارات، ويرى الـ diff وقواعد المشروع فقط، ويقيّم النتيجة بنظرة جديدة. وهذا هو المبدأ نفسه في فريق حقيقي: المؤلف لا يقبل طلب الدمج الخاص به.

• امنح المراجع أدوات القراءة وتشغيل الفحوص فقط، دون صلاحية تعديل الملفات. فلن يبدأ «بالإصلاح الصامت» بدل الإبلاغ عن المشكلة.
• اكتب معايير الفحص صراحة: ما الذي يُعد خطأً، وأي قواعد للمشروع إلزامية.
• اترك القرار فيما يُفعل بالملاحظات للمنسّق أو للإنسان. المراجع يكتشف، والمنفذ يصلح.

المراجع لا يحل محل الفحوص الآلية. الاختبارات والمدقق اللغوي وفحص الأنواع عقد حتمية، وهي أوثق من أي نموذج. المراجع يلتقط ما لا تراه الآلة: منطقاً خاطئاً، ومخالفة لاتفاقات، وتعقيداً زائداً.

التشغيل المتوازي للوكلاء الفرعيين

يستطيع Claude Code تشغيل عدة وكلاء فرعيين في آن واحد. وهذا يسرّع العمل حين تكون أجزاء المهمة مستقلة فعلاً: دراسة ثلاث وحدات، أو مراجعة التغييرات من ثلاث زوايا (الأمان والأداء والاختبارات)، أو جمع معلومات من عدة مصادر.

التوازي يعمل جيداً مع القراءة ويعمل سيئاً مع الكتابة. إذا عدّل منفذان الملفات نفسها في الوقت ذاته فسيمحو كل منهما تعديلات الآخر دون أن يعلم أي منهما. في لغة رسم الوكلاء هذه هي حالة مشتركة بلا قاعدة دمج. قواعد عملية:

• التوازي للاستكشاف والتحليل والمراجعة. والتعديلات على الملفات المتقاطعة تكون متسلسلة.
• إذا كتب المنفذون بالتوازي فافصل المناطق: كل واحد يعمل في ملفاته فقط، أو في نسخته الخاصة من المستودع (مثلاً في git worktree منفصل).
• من يدمج النتائج هو عقدة واحدة، أي المنسّق، لا المنفذون فيما بينهم.

متى لا تحتاج إلى وكلاء فرعيين؟

النظام متعدد الوكلاء له ثمن: مزيد من الـ tokens، ومزيد من الوقت، ومزيد من المواضع التي تضيع فيها المعلومات أثناء النقل. والوكلاء الفرعيون في Claude Code لا يستحقون هذا الثمن دائماً.

قبل أن تبني رسماً بيانياً من الوكلاء أجب عن أسئلة بسيطة: من يملك الهدف المشترك؟ ومن يستطيع الاعتراض والتراجع عن تغيير؟ وما المقاييس التي تُعد نجاحاً؟ إن لم تكن لديك إجابات فإن الوكلاء المتعددين سيضاعفون فوضى الوكيل الواحد فقط.

أخطاء شائعة مع الوكلاء الفرعيين

وصف غامض

الوصف «مساعد للشيفرة» لا يساعد الوكيل الرئيسي على اختيار متى يستدعيه. اكتب المحفّز: «بعد تغييرات في مجلد api/، وقبل الـ commit».

تكليف بلا سياق

يتلقى الوكيل الفرعي مهمة دون مسارات ولا معايير إنجاز ولا قيود، فيقضي نصف العمل في تخمين المطلوب. العلاج قالب للتكليف: الهدف، والمدخلات، والقيود، وشكل الرد.

صلاحيات أوسع من اللازم

المستكشف والمراجع لا يحتاجان صلاحية تعديل الملفات. وتقييد tools طريقة رخيصة لتحويل الدور إلى آلية، لا إلى طلب مكتوب في التعليمات.

الثقة في التقرير دون تحقق

عبارة «كل الاختبارات نجحت» في رد الوكيل الفرعي ادعاء وليست حقيقة. على المنسّق أن يعتمد على ما يمكن التحقق منه: مخرجات الأمر، ورمز الخروج، وأسطر محددة.

خلاصة

الوكلاء الفرعيون في Claude Code أداة لثلاث مهام: إبقاء السياق الرئيسي نظيفاً، وفصل الفحص عن التنفيذ، وتوزيع العمل المستقل على عدة مسارات. يُوصف كل منهم بملف Markdown قصير في .claude/agents/، وتعتمد جودة عمله تقريباً على وصف دوره، ومجموعة أدواته، ومدى اكتفاء التكليف بذاته. وحين تكون المهمة صغيرة أو مترابطة بقوة مع الحوار يظل الوكيل الواحد هو الأفضل. أما الانتقال من حلقة واحدة إلى منظومة من العقد والحواف والحالة المشتركة فيُشرح بالتطبيق العملي في الدورة.