Claude Code subagents: كيف يعمل الوكلاء الفرعيون ومتى تستخدمهم؟

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

خلاصة Claude Code subagents في 20 ثانية

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

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

ما المقصود فعليًا بـ Claude Code subagents؟

يعمل الوكيل الفرعي داخل نافذة سياق خاصة به، وفق موجّه نظام مخصص، وصلاحيات مستقلة، ووصول محدد إلى الأدوات. عندما يواجه Claude مهمة تطابق الوصف الوظيفي للوكيل، يُسندها إليه؛ فيعمل الوكيل باستقلال ثم يعيد النتيجة. هذا هو التعريف الرسمي، وأهم جزأين فيه هما نافذة سياق خاصة وإعادة النتيجة.

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

لهذا العزل مكسب وتكلفة، وفهم المقايضة بينهما هو أساس الاستخدام الصحيح:

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

الملف الذي يعرّف الوكيل الفرعي

يُعرَّف الوكيل الفرعي المخصص في ملف Markdown يتضمن مقدمة YAML. المقدمة هي الإعدادات، أما نص Markdown فيصبح موجّه النظام الخاص بالوكيل. ولا يلزم سوى حقلين: name وdescription.

---
name: code-reviewer
description: Reviews code for quality and best practices. Use immediately after writing or modifying code.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. When invoked, run git diff to see recent
changes, focus on modified files, and review for clarity, naming, error
handling, exposed secrets, input validation, and test coverage. Group your
feedback by priority: critical issues, warnings, then suggestions.

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

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

أين تُحفظ ملفات الوكلاء الفرعيين، وأي تعريف له الأولوية؟

يتصرف ملف الوكيل الفرعي نفسه بصورة مختلفة بحسب مكان حفظه؛ فالموقع يحدد من يستطيع استخدامه وأي تعريف يفوز عند تكرار الأسماء.

إذا حمل وكيلان الاسم نفسه، يفوز التعريف الموجود في الموقع الأعلى أولوية: التعريفات المُدارة تتقدم على تعريفات المشروع، وتعريفات المشروع تتقدم على تعريفات المستخدم. ويكتشف Claude وكلاء المشروع عبر الصعود من مجلد العمل، واعتبارًا من v2.1.178 يفوز عند تعارض الأسماء التعريف الأقرب إلى مجلد العمل. وهناك خيار خاص بالجلسة أيضًا: مرّر الوكلاء بصيغة JSON عبر الخيار --agents عند تشغيل Claude Code، فيبقون لتلك الجلسة فقط من دون حفظهم على القرص، وهي طريقة مناسبة لسكربتات الأتمتة والاختبارات السريعة.

القاعدة العملية بسيطة: إذا كان الوكيل يجسّد طريقة مراجعة أو اختبار خاصة بقاعدة الشفرة هذه، فمكانه .claude/agents/ ويجب إدخاله في نظام التحكم بالإصدارات ليستفيد منه الفريق كله. أما الوكيل الذي يعكس أسلوبك الشخصي في العمل، فمكانه ~/.claude/agents/ كي يصاحبك في جميع المشاريع.

النموذج والأدوات: إعدادان يصنعان الفارق

يقوم حقلان في المقدمة بمعظم العمل الحقيقي. وضبطهما جيدًا هو ما ينقل الوكلاء الفرعيين من فكرة لطيفة إلى أداة مجدية من حيث التكلفة.

النموذج. يقبل حقل model اسمًا مختصرًا (sonnet أو opus أو haiku أو fable)، أو معرّف نموذج كاملًا مثل claude-opus-4-8، أو القيمة inherit. وإذا حذفته، تكون القيمة الافتراضية inherit، أي إن الوكيل الفرعي يستخدم نموذج المحادثة الرئيسية نفسه. هنا توجد أداة مهمة لضبط الميزانية. فالوكيل الذي لا تتجاوز مهمته «البحث عبر grep في قاعدة الشفرة وتلخيص النتائج» لا يحتاج إلى نموذج متقدم؛ اضبطه على model: haiku ليتولى نموذج أسرع وأقل تكلفة هذا العمل الروتيني، بينما تبقى جلستك الرئيسية على Opus للمهام التي تحتاج إلى تفكير.

الأدوات. يرث الوكيل الفرعي افتراضيًا جميع الأدوات الداخلية وأدوات MCP المتاحة في محادثتك الرئيسية. ويمكن تضييق ذلك بأحد حقلين: tools قائمة سماح، فلا يتاح سواها، وdisallowedTools قائمة منع، فتتاح الأدوات كلها عدا المذكور فيها. مثلًا، يمكن منح وكيل بحث يجب ألا يلمس ملفاتك الإعداد tools: Read, Grep, Glob, Bash، وعندها لن يستطيع تعديل أي شيء أصلًا. ليست هذه مجرد مسألة ترتيب؛ بل حد أمان حقيقي، لأن المراجع المقيّد بالقراءة فقط لا يمكنه أن يعيد كتابة الملف الذي يراجعه عن طريق الخطأ.

وهناك إعداد آخر يستحق الانتباه: يشغّل isolation: worktree الوكيل الفرعي داخل git worktree مؤقت، أي نسخة معزولة من المستودع، وتُنظف تلقائيًا إذا لم يُجرِ الوكيل أي تغييرات. استخدمه عندما تريد من الوكيل تجربة أمر محفوف بالمخاطر من دون أن يتداخل مع شجرة عملك.

متى تستخدم الوكيل الفرعي، ومتى تتجنبه؟

هذا هو الجزء الذي تغفله ملفات إعداد GitHub الطويلة، مع أنه الأكثر قدرة على توفير الوقت والمال. الوكيل الفرعي ليس مجانيًا، لذلك لا تسأل «هل يمكنني استخدامه هنا؟»، بل اسأل «هل يعوّض العزل تكلفته هنا؟».

وفي الحالات التالية، يكون الوكيل الفرعي هو الأداة الخطأ بحكم طريقة تصميم الميزة نفسها:

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

الوكيل الفرعي أم Skill أم Fork أم Agent team؟

يوفر Claude Code الآن أربع طرق لتنظيم العمل، ومن السهل الخلط بينها. والفارق بينها كله يتعلق بالسياق.

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

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

القدرات المتقدمة وحدودها

تجعل ميزتان أحدث الوكلاء الفرعيين أقوى بكثير، ولكل منهما حد مهم ينبغي احترامه.

التداخل. اعتبارًا من Claude Code v2.1.172، يستطيع الوكيل الفرعي تشغيل وكلاء فرعيين تابعين له. فيمكن لوكيل مراجعة أن يرسل وكيل تحقق لكل ملاحظة، وتظل كل التفاصيل الوسيطة مخفية؛ إذ لا يصل إلى المحادثة الرئيسية سوى ملخص الوكيل الأعلى. لكن الحد ثابت: يصل التداخل إلى خمسة مستويات، ولا يمكن تغييره، والوكيل في المستوى الخامس لا يحصل على أداة Agent، لذلك لا يستطيع تشغيل المزيد. لهذا السقف سبب وجيه؛ فالتوسع المتشعب والعميق قد يطلق سربًا بلا قصد ويرفع استهلاك التوكنات سريعًا، لذا تعامل مع العمق كميزانية لا كهدف.

الذاكرة. أضف memory: project، أو user أو local، ليحصل الوكيل الفرعي على مجلد ذاكرة دائم يقرأ منه ويكتب إليه عبر الجلسات. وهكذا يبني وكيل مراجعة الشفرة المزود بذاكرة على مستوى المشروع سجلًا لتقاليدك والمشكلات المتكررة، فيتحسن مع كل استخدام. الخيار project هو الإعداد الافتراضي الموصى به لأنه قابل للمشاركة عبر نظام التحكم بالإصدارات. وعند تفعيل الذاكرة، يحقن Claude Code أول 200 سطر، أو 25KB، من ملف MEMORY.md الخاص بالوكيل في موجّه النظام عند بدء التشغيل، لذا حافظ على هذا الملف منظمًا ومنتقى.

أفضل بداية هي إنشاء وكيل فرعي واحد محدد المهمة — ومراجع الشفرة بصلاحية القراءة فقط code-reviewer هو المثال المعتاد — ثم إضافته إلى .claude/agents/ وإدخاله في نظام التحكم بالإصدارات، وتركه يعمل بعد كل تغيير. وبعد أن يثبت قيمته، أضف وكيل بحث يستخدم نموذجًا أقل تكلفة. الفرق التي تحقق فائدة هنا لا تشغّل ثلاثين وكيلًا؛ بل تشغّل ثلاثة، ولكل واحد منهم مهمة واحدة يتقنها. وإذا كان سؤالك الأساسي هو اختيار أداة البرمجة، فهذا قرار مختلف تناولته في Codex vs Claude Code vs Cursor، إلى جانب نظرة أوسع في أفضل وكلاء البرمجة بالذكاء الاصطناعي.

إذا كنت تدمج Claude Code في طريقة تسليمك الفعلية للمنتجات، فهذا هو محور معظم ما أكتب عنه. اشترك في النشرة البريدية لتحصل على إعدادات العمل المجربة، بعيدًا عن ضجيج يوم الإطلاق.