كيفية إنشاء وكلاء فرعيين مخصصين لأكواد كلود (دليل التكوين)

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

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

اختصار للملخص

يمكنك إنشاء وكيل فرعي في Claude Code بكتابة ملف Markdown في .claude/agents/ يحتوي على بيانات YAML الأولية: name (الاسم)، وdescription (الوصف) الذي يخبر كلود متى يجب التفويض، وقائمة سماح اختيارية tools (الأدوات)، وmodel (النموذج) اختياريًا. يصبح نص الملف هو موجه النظام للوكيل الفرعي. يعمل كل وكيل فرعي في نافذة السياق الخاصة به مع أدواته الخاصة، مما يوفر لك عزل السياق والتوازي والتخصص. يفوض كلود تلقائيًا بناءً على الوصف، أو يمكنك استدعاء وكيل فرعي بالاسم. المرجع الرسمي هو وثائق الوكلاء الفرعيين في Claude Code.

الوكلاء الفرعيون في 60 ثانية

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

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

هذا هو الأساس المفاهيمي؛ النظرة العامة المفاهيمية تتعمق أكثر في السبب. بقية هذا الدليل تدور حول بنائها، وهو نفس المبدأ وراء بنية تسخير وكلاء Claude Code المطبقة على مستوى المهام الفردية.

لماذا تستخدم الوكلاء الفرعيين؟

ثلاثة أسباب، وهي تتراكم.

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

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

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

كيفية إنشاء وكيل فرعي مخصص

الوكلاء الفرعيون هي ملفات Markdown عادية. ضع الملفات الخاصة بالمشروع في .claude/agents/ والملفات الشخصية في ~/.claude/agents/. يحتوي كل ملف على بيانات YAML الأولية ونص يصبح موجه نظام الوكيل الفرعي.

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

أنت مراجع كود متمرس. عند إعطائك فرقًا (diff) أو مجموعة من الملفات:

1. ابحث عن أخطاء التصحيح، والثغرات الأمنية، وحالات الحافة التي تم تفويتها.
2. تحقق من أن الكود يتطابق مع اتفاقيات المشروع الحالية.
3. أبلغ عن المشكلات عالية الثقة فقط، مرتبة حسب الخطورة.

كن محددًا. اذكر الملف والسطر. لا توافق دون مراجعة دقيقة.

حقول البيانات الأولية:

• name — المعرف الذي تستخدمه لاستدعائه.
• description — هذا هو الحقل المهم. يقرأ كلود هذا الحقل ليقرر متى يفوض تلقائيًا. اكتبه كمنشط واضح ("استخدم بعد كتابة الكود")، وليس كتسمية غامضة.
• tools — قائمة السماح. احذفها لترث أدوات الوكيل الرئيسي، أو اذكر أدوات محددة للتقييد. المراجع الذي لا يستطيع كتابة الكود لا يمكنه تغييره عن طريق الخطأ.
• model — اختيارياً حدد نموذجًا. استخدم نموذجًا أرخص وأسرع للوكلاء الفرعيين الميكانيكيين ونموذجًا أقوى للتفكير الصعب.

النص هو موجه النظام. هنا يكمن التخصص، لذا اكتبه كما لو كنت تقدم إحاطة لموظف جديد: ما يجب فعله، وما يجب إعطاؤه الأولوية، وما يجب تجنبه. إقرانه بملف مشروع design.md أو AGENTS.md يمنح الوكيل الفرعي اتفاقياتك دون تكرارها في كل ملف.

كيفية استدعاء الوكلاء الفرعيين

هناك طريقتان لتشغيل الوكيل الفرعي.

• التفويض التلقائي. يقرأ كلود حقل description (الوصف) لكل وكيل فرعي متاح ويفوض بنفسه عندما تتطابق المهمة. بعد الانتهاء من تحرير ملف، قد يسلم الوكيل الرئيسي الفرق (diff) إلى code-reviewer (مراجع الكود) الخاص بك دون توجيه، لأن الوصف يقول "استخدم بعد كتابة الكود". الأوصاف الجيدة تقود إلى تفويض جيد.
• الاستدعاء الصريح. يمكنك أيضًا تسميته مباشرة: "استخدم الوكيل الفرعي لمراجعة الكود على التغييرات في وحدة الطلبات." هذه هي الطريقة التي تفرض بها متخصصًا معينًا عندما لا ترغب في ترك التفويض للصدفة.

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

الوكلاء الفرعيون مقابل Agent SDK مقابل سير العمل الديناميكي

هذه تتداخل، لذا إليك متى يناسب كل منها.

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

مثال عملي: مراجعة متوازية وكتابة اختبارات

لنجمعها معًا. لنفترض أنك جعلت الوكيل الرئيسي ينفذ نقطة نهاية (endpoint) جديدة للطلبات. تريد مراجعتها واختبارها، ولا يوجد سبب لحدوث ذلك بشكل تسلسلي.

حدد وكيلين فرعيين. code-reviewer (مراجع الكود) المذكور أعلاه، بالإضافة إلى كاتب اختبار:

---
name: api-test-writer
description: يكتب حالات اختبار واجهة برمجة التطبيقات (API) لنقاط النهاية الجديدة أو المتغيرة. استخدمه بعد تنفيذ نقطة النهاية.
tools: Read, Grep, Write, Bash
model: sonnet
---

أنت تكتب اختبارات واجهة برمجة التطبيقات (API) مقابل مواصفات OpenAPI للمشروع.

1. اقرأ المواصفات وتنفيذ نقطة النهاية.
2. اكتب اختبارات تغطي النجاح وأخطاء التحقق والمصادقة.
3. تأكد من رموز الحالة وتحقق من محتوى الاستجابات مقابل المخطط (schema).
4. قم بتشغيل المجموعة وأبلغ عن النجاح/الفشل مع ذكر الأسباب.

الآن، يرسل الوكيل الرئيسي كلاهما في وقت واحد: يقرأ المراجع الفرق (diff) بينما يقرأ كاتب الاختبار المواصفات ويكتب التغطية. متخصصان، وسياقان معزولان، يعملان بالتوازي. يظل المسار الرئيسي نظيفًا ويسترجع ملخصين: تقرير مراجعة ونتيجة اختبار.

نتيجة الاختبار هذه هي الجزء الذي يجعل هذا موثوقًا به. الوكيل الفرعي الذي يشغل مجموعة اختبارات واجهة برمجة التطبيقات (API) الخاصة بك هو بوابة تحقق، الفحص الحتمي الذي يحدد ما إذا كانت نقطة النهاية تعمل بالفعل بدلاً من مجرد مظهرها المكتمل. هذه هي الفكرة الأساسية من حلقات وكلاء البرمجة: ثقة الوكيل نفسه لا تُحتسب، بل حكم البوابة هو الذي يُحتسب. قم بتوصيل الوكيل الفرعي للاختبار بمنصة اختبار API حقيقية وتصبح الملاحظات أكثر دقة. تشير الفرق التي تستخدم Apidog بالوكيل الفرعي إلى سيناريو اختبار Apidog بحيث يتم التحقق من صحة كل استجابة وفقًا للمخطط (schema)، وتوجه استدعاءات نقطة النهاية المباشرة للوكيل عبر مصحح أخطاء وكيل Apidog AI بحيث يفحص الطلبات بالطريقة التي يفحصها بها المختبر البشري. خذ نفس الإعداد، لفه في حلقة، وستحصل على سير العمل غير المراقب الذي بنيناه في سير عمل Claude الذي يعمل بدونك. قم بتنزيل Apidog إذا كنت تريد أن تكون بوابة الاختبار مدركة للمخطط (schema-aware) جاهزة للاستخدام.

أفضل الممارسات

بعض العادات تحافظ على فائدة الوكلاء الفرعيين بدلاً من الفوضى.

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

تعكس هذه الأنماط أنماط التوصيل التي غطيناها في توصيل أدوات سير عمل الوكيل، وهي تنطبق سواء كان لديك وكيلان فرعيان أو عشرون.

متى تلجأ إلى الوكلاء الفرعيين (ومتى لا تلجأ إليها)

الوكلاء الفرعيون أداة، وليست خيارًا افتراضيًا. معرفة متى تتخطاها يحافظ على إعدادك سريعًا ورخيصًا.

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

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

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

الأخطاء الشائعة

• أوصاف غامضة. إذا كان description (الوصف) مجرد تسمية، فلن يتم تشغيل التفويض التلقائي عندما تتوقع ذلك. اكتبه كمنشط للاستخدام.
• وكيل فرعي واحد متضخم. حشر كل مهمة في وكيل فرعي واحد يلغي فائدة التخصص. قسّم المهام حسب المسؤولية.
• وراثة جميع الأدوات افتراضيًا. ترك tools (الأدوات) غير محدد يمنح الوكيل الفرعي كل ما يمتلكه الوكيل الرئيسي. هذا جيد للعمل الموثوق به، ومحفوف بالمخاطر لأي شيء مؤتمت. قم بتحديد قائمة السماح بعناية.
• لا يوجد وكيل فرعي للتحقق. إعداد للمراجعة والبناء بدون بوابة اختبار ينتج كودًا يبدو صحيحًا ولكنه يتعطل عند الحواف. قم دائمًا بتضمين وكيل فرعي يقوم بتشغيل الاختبارات بالفعل.
• معاملة الوكلاء الفرعيين كـ SDK. يتم إرسال الوكلاء الفرعيين بواسطة النموذج ويكونون ضمن الجلسة. إذا كنت تحتاج إلى تدفق تحكم حتمي ومجدول، فهذه مهمة Agent SDK، وليست مجموعة من الوكلاء الفرعيين.

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

الأسئلة المتكررة

• ما هو الوكيل الفرعي في Claude Code؟ هو نسخة وكيل منفصلة يفوضها وكيل Claude Code الرئيسي. يمتلك كل وكيل فرعي نافذة سياق خاصة به، وموجه نظام مخصص، ومجموعة أدوات قابلة للتكوين. يقوم بمهمة مركزة ويعيد النتيجة، مما يحافظ على نظافة المحادثة الرئيسية ويتيح لك تشغيل المتخصصين بالتوازي.
• كيف أقوم بإنشاء وكيل فرعي في Claude Code؟ أنشئ ملف Markdown في .claude/agents/ (للمشروع) أو ~/.claude/agents/ (شخصي). أضف بيانات YAML الأولية مع name (الاسم)، وdescription (الوصف)، وtools (الأدوات) الاختيارية، وmodel (النموذج) الاختياري، ثم اكتب موجه النظام في النص. يخبر الوصف كلود متى يفوض إليه تلقائيًا.
• كيف يقرر كلود أي وكيل فرعي يستخدم؟ يقرأ حقل description (الوصف) لكل وكيل فرعي متاح ويفوض تلقائيًا عندما تتطابق المهمة. يمكنك أيضًا استدعاء وكيل فرعي بالاسم صراحةً، مثل "استخدم الوكيل الفرعي لمراجعة الكود." الأوصاف الواضحة بأسلوب المنشط تجعل التفويض التلقائي موثوقًا به.
• ما الفرق بين الوكلاء الفرعيين و Claude Agent SDK؟ الوكلاء الفرعيون يعملون داخل الجلسة ويتم إرسالهم بواسطة النموذج: أنت تعمل في Claude Code وهو يستدعي المتخصصين. أما Agent SDK فهو برمجي، حيث تكتب تدفق التحكم في الكود لتشغيل حتمي أو غير مراقب. استخدم الوكلاء الفرعيين للتخصص التفاعلي، و SDK للحلقات المجدولة.
• هل يمكن للوكلاء الفرعيين العمل بالتوازي؟ نعم. يمكن للوكيل الرئيسي إرسال عدة وكلاء فرعيين في وقت واحد للمهام المستقلة، بحيث تحدث المراجعة والاختبار والتوثيق معًا بدلاً من التسلسل. للتوسع الكبير، يوسع سير العمل الديناميكي في Claude Code هذا ليشمل العديد من الوكلاء الفرعيين المتوازيين في جلسة واحدة.
• كيف يساعد الوكلاء الفرعيون في اختبار واجهة برمجة التطبيقات (API)؟ حدد وكيلًا فرعيًا يقوم بكتابة وتشغيل اختبارات واجهة برمجة التطبيقات (API) الخاصة بك مقابل مواصفات OpenAPI. يصبح هذا بمثابة بوابة تحقق تتأكد مما إذا كانت نقطة النهاية تعمل بالفعل، وليس فقط إذا كانت تبدو مكتملة. توجيهها إلى منصة مثل Apidog يجعل الملاحظات مدركة للمخطط (schema-aware)، بحيث يتم التحقق من صحة كل استجابة مقابل العقد.

الخلاصة

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

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