الوكلاء الفرعيون في Claude Code (subagents): دليل عملي لكتابة وكلائك

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

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

يتغير Claude Code بسرعة. كل ما يلي يطابق التوثيق الرسمي للوكلاء الفرعيين حتى أواخر 2026، لكن راجع توثيق إصدارك قبل الاعتماد على حقل معيّن.

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

الوكيل الفرعي مساعد متخصص يمكن لجلسة Claude Code الرئيسية أن تفوّض إليه. ثلاثة أشياء تجعله مفيدًا:

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

والمقابل أن الوكيل الفرعي يبدأ من الصفر. لا يعرف إلا ما تقوله له رسالة التفويض، لذا فجودة هذا التسليم مهمة.

أين توضع الملفات

الوكيل الفرعي ملف Markdown في أعلاه قسم إعداد بصيغة YAML. والمكانان الأكثر استخدامًا:

• .claude/agents/ داخل المستودع، لوكلاء المشروع. أضفها إلى نظام التحكم في النسخ ليتشارك الفريق كله الوكلاء أنفسهم.
• ~/.claude/agents/ في مجلدك الشخصي، لوكلاء متاحين في كل مشاريعك.

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

حقول الإعداد المهمة

حقلان فقط إلزاميان:

• name: معرّف فريد، مثل code-reviewer.
• description: متى يجب أن يفوّض Claude إلى هذا الوكيل. وهذا أهم سطر في الملف.

والحقول الاختيارية التي أستخدمها أكثر:

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

هناك حقول أخرى (hooks وskills وخوادم MCP والذاكرة وغيرها)، لكنك تستطيع الذهاب بعيدًا بهذه الحقول.

كيف يعمل التفويض

يفوّض Claude تلقائيًا عندما تطابق مهمةٌ حقل description لوكيل فرعي. وكتابة عبارة "use proactively" في الوصف تشجعه على التفويض دون أن يُطلب منه.

ويمكنك أن تكون صريحًا:

• بالاسم، بلغة عادية: "استخدم الوكيل code-reviewer لمراجعة تعديلات تسجيل الدخول."
• بالإشارة @، وهذا يضمن تشغيل ذلك الوكيل بعينه.
• لجلسة كاملة، بتشغيل Claude Code مع هذا الوكيل كوكيل رئيسي.

ويأتي Claude Code أيضًا بوكلاء فرعيين مدمجين، منهم Explore (بحث سريع في الشيفرة للقراءة فقط)، وPlan (بحث للقراءة فقط يُستخدم في وضع التخطيط)، وgeneral-purpose (كل الأدوات للمهام متعددة الخطوات). قبل كتابة وكيل مخصص، تأكد أن وكيلًا مدمجًا لا يؤدي المهمة بالفعل.

مثالان على تعريف الوكلاء

وكيل مراجعة للقراءة فقط. يستطيع أن ينظر دون أن يلمس، وعليه أن يثبت كل ما يقوله:

---
name: code-reviewer
description: Reviews a diff for correctness bugs. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: inherit
maxTurns: 40
---

You review one change. Your job is to find what the author missed,
not to confirm it works.

Rules:
- Read the diff and the code it touches. Run the existing tests.
- Report only findings you can reproduce with a failing test or command.
- For each finding: file, line, what breaks, and the repro.
- If you find nothing provable, say "no findings". Do not pad the list.

ووكيل تنفيذ يعمل في عزلة ويتوقف عند بوابات الفحص:

---
name: implementer
description: Implements one scoped ticket end to end in an isolated worktree.
isolation: worktree
model: inherit
---

You implement exactly one ticket.

- Read the ticket and the relevant contract or spec first.
- Write the code and the tests together.
- Before reporting done, run lint, the full test suite and the build.
- Report: what changed, which files, gate results. If a gate fails, say so.

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

نصائح للتصميم

اكتب الوصف لمن يوزّع المهام

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

أعطِ أقل عدد من الأدوات يكفي

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

حدّد شكل المخرجات

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

مهمة واحدة لكل وكيل

"نفّذ واختبر وراجع ووثّق" هي أربعة وكلاء يتظاهرون بأنهم واحد. الوكيل ذو المهمة الواحدة والقواعد الواضحة أسهل في التصحيح عندما يخطئ.

أخطاء شائعة

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

لنعمل معًا

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