> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# الوكلاء الفرعيون Subagents والعمل بالتوازي في فروع منفصلة
- URL: https://arabroot.io/articles/الوكلاء-الفرعيون-subagents-والعمل-بالتوازي-في-فروع-منفصلة/
- Published: 2026-11-20T07:19:36.000Z
- Updated: 2026-11-20T08:19:09.000Z
- Description: كيف يعمل الوكيل الفرعي في Claude Code وCodex وCursor، ومتى يفيد عزل القراءة والكتابة في Worktree لكل وكيل، مع تجربة على نموذج محلي فيها أخطاء مزروعة وإصلاحات في فروع منفصلة وتعارض حقيقي.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, التطوير مع وكلاء الذكاء الاصطناعي

تسأل وكيل البرمجة سؤالاً بسيطاً مثل «أين نتحقق من صلاحية التوكن Token في هذا المشروع؟»، فيبدأ بالبحث، ويقرأ ثلاثين ملفاً، ويشغل `grep` عشر مرات، ثم يجيبك بسطرين صحيحين. والإجابة ممتازة، ولكن الثلاثين ملفاً بقيت كلها في نافذة السياق Context Window، وعندما تطلب منه الآن أن يكتب الإصلاح فإنه يكتبه وأمامه آلاف الأسطر التي لا علاقة لها بالإصلاح، ويدفع ثمن قراءتها من جديد في كل دورة من دورات الحلقة. ولو كان عندك زميل لقلت له «ابحث أنت وأخبرني بالنتيجة»، فيبحث هو في مكتبه، ويرجع إليك بالسطرين فقط، ويبقى مكتبك نظيفاً للقرار. وهذا بالضبط ما يفعله الوكيل الفرعي Subagent.

وفي [مقال هندسة السياق](https://arabroot.io/articles/%D9%87%D9%86%D8%AF%D8%B3%D8%A9-%D8%A7%D9%84%D8%B3%D9%8A%D8%A7%D9%82-context-engineering-%D9%85%D8%A7-%D9%8A%D8%B1%D8%A7%D9%87-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84/) ذكرنا الوكيل الفرعي كأحد أربعة أشياء تفعلها بالسياق، أي العزل Isolate، وفي [مقال المهارات Agent Skills](https://arabroot.io/articles/%D8%A7%D9%84%D9%85%D9%87%D8%A7%D8%B1%D8%A7%D8%AA-agent-skills-%D8%AA%D8%B9%D9%84%D9%8A%D9%85%D8%A7%D8%AA-%D9%8A%D8%AD%D9%85%D9%84%D9%87%D8%A7-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84-%D8%B9%D9%86%D8%AF-%D8%A7%D9%84%D8%AD%D8%A7%D8%AC%D8%A9/) رأينا أن المهارة يمكن أن تعمل في نافذة منفصلة بالحقل `context: fork`. وهذا المقال يدخل في التفاصيل: كيف يعمل الوكيل الفرعي من الداخل، وكيف تقدمه Claude Code وCodex وCursor، وما الفرق بين أن تقسم القراءة وأن تقسم الكتابة، ولماذا تحتاج الكتابة بالتوازي إلى فروع Branches منفصلة. ثم نقيس على نموذج محلي: وكيل واحد يقرأ عشرة ملفات في نافذة واحدة ليجد ستة أخطاء مزروعة، أمام عشرة وكلاء فرعيين يقرأ كل منهم ملفاً واحداً، مرة واحداً بعد الآخر ومرة اثنين معاً، ثم نعطي كل خطأ لوكيل ينفذ الإصلاح في Worktree خاص به، وندمج الفروع.

سوف نناقش في هذا المقال:

- ما هو الوكيل الفرعي، وكيف يراه الوكيل الرئيسي كأداة Tool لها مدخل ومخرج.
- ما الذي يدخل نافذة الوكيل الفرعي وما الذي يرجع منها، ومن يدفع ثمن التوكنات Tokens.
- القراءة بالتوازي والكتابة بالتوازي، ولماذا تحتاج الثانية إلى Git Worktree لكل وكيل.
- الوكلاء الفرعيون في Claude Code وCodex وCursor وGitHub Copilot بحسب توثيقها الرسمي.
- مختبر بالأرقام: نافذة واحدة طويلة أمام عشر نوافذ قصيرة، والتوازي، والإصلاح في فروع منفصلة، والتعارض Conflict.
- كيف تكتب وكيلاً فرعياً جيداً، والأخطاء الشائعة، وقائمة تحقق.

## ما هو الوكيل الفرعي Subagent؟

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

وتوثيق [الوكلاء الفرعيين في Claude Code](https://code.claude.com/docs/en/sub-agents?ref=arabroot.io) يصفهم بأنهم مساعدون متخصصون في أنواع محددة من المهام، كل منهم يعمل في نافذة سياق خاصة به، بتعليمات نظام System Prompt خاصة، وأدوات محددة، وصلاحيات Permissions مستقلة. وتوثيق [تعدد الوكلاء في OpenAI Agents SDK](https://openai.github.io/openai-agents-python/multi%5Fagent/?ref=arabroot.io) يسمي النمط نفسه «الوكلاء كأدوات Agents as Tools»: وكيل مدير يبقى مسؤولاً عن المحادثة، ويستدعي الوكلاء المتخصصين بالدالة `Agent.as_tool()`. والفكرة واحدة في الأدوات كلها، والاختلاف في التفاصيل: أين تكتب تعريف الوكيل، وما الأدوات التي يرثها، وهل يعمل في الخلفية، وهل يستطيع أن يشغل وكيلاً فرعياً آخر.

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

## كيف يعمل الوكيل الفرعي من الداخل؟

لنأخذ سؤال التوكن من بداية المقال، ونتتبعه خطوة بخطوة كما يحدث داخل بيئة التشغيل Harness التي شرحناها في [مقال بيئة تشغيل الوكيل](https://arabroot.io/articles/%D8%A8%D9%8A%D8%A6%D8%A9-%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84-harness-%D8%A7%D9%84%D8%AD%D9%84%D9%82%D8%A9-%D9%88%D8%A7%D9%84%D8%B5%D9%84%D8%A7%D8%AD%D9%8A%D8%A7%D8%AA-%D9%88%D8%A7%D9%84%D8%B5%D9%86%D8%AF%D9%88%D9%82-%D8%A7%D9%84%D9%85%D8%B9%D8%B2%D9%88%D9%84/):

1. الوكيل الرئيسي يقرأ سؤالك، ويرى في قائمة أدواته أداة لتشغيل وكيل فرعي، اسمها في Claude Code مثلاً `Agent`، ووصفها يقول متى تستعمل، ويقرر أن البحث في المستودع مهمة مناسبة لها.
2. يكتب الوكيل الرئيسي مدخل الأداة: نوع الوكيل الفرعي، مثل وكيل البحث Explore، ووصفاً للمهمة مثل «ابحث عن كل مكان نتحقق فيه من التوكن، وأرجع المسار ورقم السطر واسم الدالة».
3. بيئة التشغيل تبدأ حلقة جديدة: تعليمات نظام خاصة بهذا النوع من الوكلاء، وأدوات محدودة، مثل القراءة والبحث دون الكتابة، ووصف المهمة كرسالة أولى. ولا يدخل في هذه النافذة شيء من محادثتك مع الوكيل الرئيسي إلا ما كتبه في الوصف.
4. الوكيل الفرعي يعمل كأي وكيل: يبحث ويقرأ ويكرر، وقد يستهلك عشرات الآلاف من التوكنات في نافذته.
5. عندما ينتهي، ترجع رسالته الأخيرة فقط إلى الوكيل الرئيسي كنتيجة للأداة، أي سطور قليلة، وتختفي نافذته.
6. الوكيل الرئيسي يكمل بنافذة فيها سؤالك، ومدخل الأداة، والنتيجة القصيرة.

في الخطوات أعلاه لاحظ التالي:

- الخطوة الثانية هي أهم خطوة، لأن وصف المهمة هو كل ما يعرفه الوكيل الفرعي عن الدنيا، فإذا نسي الوكيل الرئيسي أن يذكر أن المشروع فيه مجلد `legacy/` لا يستعمل، فسوف يرجع الوكيل الفرعي بنتائج منه.
- الخطوة الخامسة هي الفائدة: نافذة الوكيل الرئيسي لم تكبر إلا بسطور، ولكن التوكنات التي استهلكها الوكيل الفرعي في الخطوة الرابعة لم تختف من الفاتورة، فصفحة [التكاليف في Claude Code](https://code.claude.com/docs/en/costs?ref=arabroot.io) تقول صراحة إن طلبات الوكيل الفرعي نفسه تحسب من استخدامك، وإن كل وكيل فرعي يرسل طلباته فوق طلبات المحادثة الرئيسية.
- الوكيل الفرعي لا يستطيع أن يسألك سؤالاً في منتصف عمله في أغلب الأدوات، فإذا كانت المهمة غامضة فسوف يختار تفسيراً بنفسه ويكمل.

![خط زمني لنافذتين: في الأعلى نافذة الوكيل الرئيسي فيها السؤال ثم استدعاء أداة Agent ثم نتيجة من ثلاثة أسطر، وفي الأسفل نافذة الوكيل الفرعي تبدأ بوصف المهمة وتمتلئ بقراءة ملفات وعمليات grep حتى عشرات الآلاف من التوكنات، ثم يخرج منها سهم واحد رفيع إلى النافذة الرئيسية، وعداد الفاتورة يجمع النافذتين](https://arabroot.io/content/images/2026/11/subagents-parallel-01-inside.webp)

نافذة الوكيل الرئيسي تكبر بسطور فقط، ولكن الفاتورة تجمع توكنات النافذتين

## القراءة بالتوازي أسهل بكثير من الكتابة بالتوازي

إذا كان عندك عدة وكلاء فرعيين فإن تشغيلهم معاً بالتوازي Parallel يختصر الوقت، وهذا هو السبب الثاني لتعدد الوكلاء الذي ذكرناه في [مقال تعدد الوكلاء](#related) في هذه المرحلة. ولكن هناك فرقاً كبيراً بين نوعين من العمل بالتوازي:

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

والحل المعروف للكتابة بالتوازي هو الحل نفسه الذي يستعمله فريق البشر: كل واحد في فرعه Branch. ولأن الوكلاء يعملون على جهاز واحد، فإن الفرع وحده لا يكفي، لأن مجلد العمل Working Directory واحد، وهنا يأتي [الأمر git worktree](https://git-scm.com/docs/git-worktree?ref=arabroot.io)، الذي ينشئ مجلد عمل إضافياً للمستودع نفسه على فرع مختلف، فيكون لكل وكيل مجلده وفرعه، وتبقى قاعدة البيانات الداخلية للمستودع Repository واحدة، فلا تنسخ التاريخ كله لكل وكيل. وقد شرحنا الـ Worktrees وطريقة الرجوع الآمن بالتفصيل في مقال Git مع الوكلاء في مرحلة سير العمل، وهنا نستعملها فقط.

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

⚠️

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

![مستودع Git واحد في المنتصف عليه الفرع main، وتخرج منه ثلاثة مجلدات Worktree لكل منها فرع fix/paging وfix/dates وfix/tokens ووكيل يعمل فيه، ثم ترجع الفروع الثلاثة بأسهم خضراء إلى main عند الدمج، وفي الأسفل سهمان أحمران من وكيلين إلى الملف نفسه pricing.py مع علامة تعارض](https://arabroot.io/content/images/2026/11/subagents-parallel-02-worktrees.webp)

لكل وكيل مجلد وفرع، والمستودع واحد، والتعارض يظهر عند الدمج إذا لمس وكيلان الملف نفسه

## الوكلاء الفرعيون في الأدوات المعروفة

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

### Claude Code: ملفات في `.claude/agents/`

يأتي Claude Code بوكلاء فرعيين جاهزين، منهم وكيل الاستكشاف Explore للقراءة فقط، ممنوع من الكتابة والتعديل، ويستعمل للبحث في الكود، ووكيل التخطيط Plan للقراءة فقط أيضاً، ويستعمل في وضع التخطيط Plan Mode، ووكيل عام General-purpose بكل الأدوات للمهام المعقدة وتعديل الكود. وتستطيع أن تعرف وكيلك الخاص في ملف Markdown في المجلد `.claude/agents/` للمشروع، أو `~/.claude/agents/` لك أنت، والملف يبدأ بترويسة YAML Frontmatter الحقلان الإلزاميان فيها `name` و`description` فقط، ثم تعليمات النظام في باقي الملف. ومن الحقول الاختيارية `tools` لتحديد الأدوات، و`model` لاختيار نموذج أرخص مثل `haiku`، و`isolation: worktree` لتشغيل الوكيل في Worktree مؤقتة تتفرع من الفرع الرئيسي وتحذف تلقائياً إذا لم يغير الوكيل شيئاً.

والتوثيق يذكر أيضاً أن الوكلاء الفرعيين الذين يشغلهم Claude من المحادثة الرئيسية يبدؤون في الخلفية Background افتراضياً، وأن عشرين منهم يمكن أن يعملوا معاً كحد افتراضي يتغير بالمتغير `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`، وأن الوكيل الفرعي يستطيع أن يشغل وكلاء فرعيين خاصين به حتى ثلاث طبقات تحت المحادثة الرئيسية. وهناك ميزة أخرى منفصلة اسمها [فرق الوكلاء Agent Teams](https://code.claude.com/docs/en/agent-teams?ref=arabroot.io)، وهي تجريبية ومعطلة افتراضياً وتفعل بالمتغير `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`، وفيها جلسة قائدة Team Lead وزملاء Teammates يعمل كل منهم في نافذته، ويتشاركون قائمة مهام Task List، ويرسل بعضهم لبعض رسائل مباشرة. والفرق بحسب التوثيق أن الوكلاء الفرعيين يرجعون بنتائجهم إلى الوكيل الرئيسي فقط، أما الزملاء في الفريق فيأخذون المهام من القائمة ويتكلمون مع بعضهم.

ولفرق الوكلاء في Claude Code تفاصيل تهمك إذا جربتها، وكلها من صفحة التوثيق نفسها: قائمة المهام فيها حالات معلقة وجارية ومنتهية، ويمكن أن تعتمد مهمة على أخرى، والزميل يأخذ المهمة بقفل ملف File Locking حتى لا يأخذها اثنان معاً، ولكل زميل صندوق بريد Mailbox في ملف JSON تحت `~/.claude/teams/`. والتوثيق ينصح بأن تبدأ بثلاثة إلى خمسة زملاء، ويقول إن تكلفة التوكنات تكبر خطياً مع عددهم، ويذكر قيوداً واضحة: جلسة واحدة لكل فريق، ولا فرق داخل فرق، والقائد ثابت لا يتغير، ولا يمكن استكمال الجلسة بعد إغلاقها مع الزملاء الذين يعملون داخل العملية نفسها In-process. وهذه القيود طبيعية لميزة تجريبية، ولكنها تعني أن الوكلاء الفرعيين العاديين هم الخيار الأثبت اليوم للعمل اليومي.

والمثال التالي وكيل فرعي للمراجعة يقرأ فقط ويستعمل نموذجاً أرخص، وهو ملف `.claude/agents/bug-hunter.md`:

```markdown
---
name: bug-hunter
description: Use to check ONE Python file for functions that do not match their docstring. Give it the file path. Read-only.
tools: Read, Grep, Glob
model: haiku
---
You review exactly one file. For each function, compare the code with its docstring.
Reply with JSON only: {"function": "<name or null>", "reason": "<one sentence>"}.
Do not suggest style changes. Do not read other files unless the function imports them.
```

في الملف أعلاه لاحظ التالي:

- الوصف `description` هو ما يقرؤه الوكيل الرئيسي ليقرر متى يستعمل هذا الوكيل، لذلك كتبناه كتعليمات استعمال: لماذا، وما الذي تعطيه إياه، وأنه للقراءة فقط.
- الأدوات `tools` للقراءة والبحث فقط، فحتى لو أخطأ الوكيل في فهم مهمته فإنه لا يستطيع أن يعدل شيئاً.
- شكل المخرج محدد بـ JSON قصير، لأن هذا ما سوف يدخل نافذة الوكيل الرئيسي، وكل سطر زائد فيه يدفع ثمنه في كل دورة بعده.

### Codex: أدوار وملفات TOML ومهام في السحابة

توثيق [الوكلاء الفرعيين في Codex](https://learn.chatgpt.com/docs/agent-configuration/subagents?ref=arabroot.io) يقول إن الإصدارات الحالية تفعل سير عمل الوكلاء الفرعيين افتراضياً، وإن Codex يشغل وكلاء متخصصين بالتوازي ثم يجمع نتائجهم في رد واحد، وفيه ثلاثة أدوار جاهزة: `default` و`worker` و`explorer`. والوكيل الخاص يعرف في ملف TOML في `~/.codex/agents/` أو `.codex/agents/`، فيه على الأقل `name` و`description` و`developer_instructions`، وعدد الوكلاء الذين يعملون معاً في الجلسة يحدده الإعداد `agents.max_concurrent_threads_per_session`. والتوثيق نفسه يقول بوضوح إن سير عمل الوكلاء الفرعيين يستهلك توكنات أكثر من تشغيل مشابه بوكيل واحد.

وللعمل بالتوازي في الكتابة يقدم Codex طريقتين: [الـ Worktrees في تطبيق Codex](https://learn.chatgpt.com/docs/environments/git-worktrees?ref=arabroot.io)، حيث تعمل عدة محادثات مستقلة في المشروع نفسه دون أن تتداخل، وتنشأ الـ Worktrees تحت `$CODEX_HOME/worktrees` ويحتفظ بآخر خمس عشرة منها افتراضياً، و[المهام في السحابة Cloud Tasks](https://learn.chatgpt.com/docs/cloud?ref=arabroot.io)، حيث لكل مهمة مساحة عمل خاصة في بيئة سحابية تعدها مسبقاً، وتستمر في العمل حتى وجهازك نائم، ثم تراجع التغييرات والاختبارات وتعمل commit أو تفتح طلب دمج.

### Cursor: Worktrees محلية ووكلاء في السحابة

في Cursor تسمح [الـ Worktrees](https://cursor.com/docs/configuration/worktrees?ref=arabroot.io) للوكيل أن يعمل في نسخة Git معزولة على جهازك، بحد افتراضي خمس وعشرين Worktree للجهاز، والإعداد في الملف `.cursor/worktrees.json`، والأمر `/apply-worktree` يرجع التغييرات إلى نسختك الرئيسية، والأمر `/best-of-n` يشغل المهمة نفسها على عدة نماذج معاً، كل تشغيل في Worktree خاصة، لتختار أفضل نتيجة. أما [الوكلاء في السحابة Cloud Agents](https://cursor.com/docs/cloud-agent?ref=arabroot.io)، التي كان اسمها سابقاً Background Agents، فتعمل في أجهزة افتراضية معزولة في السحابة، تنسخ المستودع وتعمل على فرع منفصل وتخرج طلب دمج جاهزاً، وتحسب من استخدام خطتك بسعر النموذج المختار.

### GitHub Copilot: وكيل في السحابة لكل مهمة

الوكيل في GitHub، الذي يسمى اليوم في التوثيق [Copilot cloud agent](https://docs.github.com/en/copilot/concepts/copilot-surfaces/copilot-on-github?ref=arabroot.io)، يعمل في بيئة سحابية أو في GitHub Actions، ويعمل على فرع واحد في المرة، ويفتح طلب دمج واحداً لكل مهمة، وأقصى وقت للجلسة التي تعمل في GitHub Actions تسع وخمسون دقيقة. فالتوازي هنا يأتي من أنك تعطي عدة مهام لعدة جلسات، ولكل منها فرعها وطلبها، وليس من وكلاء فرعيين داخل جلسة واحدة.

| الأداة                  | أين يعمل الوكيل الفرعي أو المتوازي               | كيف تعرفه                     | عزل الكتابة                                  |
| ----------------------- | ------------------------------------------------ | ----------------------------- | -------------------------------------------- |
| Claude Code             | على جهازك، في نافذة منفصلة، في الخلفية افتراضياً | Markdown في .claude/agents/   | isolation: worktree                          |
| Claude Code Agent Teams | على جهازك، جلسة لكل زميل                         | القائد ينشئ الفريق، تجريبي    | يعتمد عليك في تقسيم الملفات                  |
| Codex                   | على جهازك أو في السحابة                          | TOML في .codex/agents/        | Worktrees في التطبيق، ومساحة لكل مهمة سحابية |
| Cursor                  | على جهازك أو في جهاز افتراضي سحابي               | من الواجهة والأوامر           | Worktrees محلية، وفرع لكل وكيل سحابي         |
| Copilot cloud agent     | في السحابة أو GitHub Actions                     | تذكرة Issue أو طلب من الواجهة | فرع وطلب دمج لكل مهمة                        |

![لوحتان: على جهازك Claude Code بملفات .claude/agents وisolation: worktree، وCodex بملفات TOML وWorktrees التطبيق، وCursor بملف worktrees.json والأمر best-of-n، وفي السحابة مهام Codex السحابية بمساحة لكل مهمة، ووكلاء Cursor السحابيون في جهاز افتراضي بفرع وطلب دمج، ووكيل Copilot السحابي بفرع واحد وطلب دمج لكل مهمة](https://arabroot.io/content/images/2026/11/subagents-parallel-05-tools.webp)

محلياً أو في السحابة، الفكرة واحدة: فرع منفصل لكل وكيل يكتب، والمراجعة والدمج عندك

## المختبر: نافذة واحدة طويلة أمام عشر نوافذ قصيرة

لكي نرى الفرق بين أن يقرأ وكيل واحد كل شيء وبين أن يقرأ كل وكيل فرعي جزءاً، بنينا مشروعاً صغيراً لمتجر في المجلد `shop/` فيه عشرة ملفات Python، في كل منها بين 19 و30 سطراً، ولكل دالة وصف Docstring يقول ماذا يجب أن تفعل. وزرعنا في ستة ملفات منها خطأً واحداً، دالة لا تفعل ما يقوله وصفها، وتركنا أربعة ملفات سليمة، ومعها اختبارات في `tests/test_all.py` تكشف الأخطاء الستة:

| الملف                                        | الدالة       | الخطأ المزروع                                                       |
| -------------------------------------------- | ------------ | ------------------------------------------------------------------- |
| pricing.py                                   | round\_money | يحذف الجزء العشري بـ int() بدل التقريب إلى الأعلى عند النصف         |
| dates.py                                     | is\_leap     | ينسى قاعدة الأربعمئة سنة، فتصبح 2000 سنة غير كبيسة                  |
| paging.py                                    | page\_count  | قسمة صحيحة بدل التقريب إلى الأعلى، فـ 41 عنصراً تعطي صفحتين         |
| tokens.py                                    | is\_expired  | المقارنة معكوسة، فالتوكن الجديد يعتبر منتهي الصلاحية والقديم صالحاً |
| text.py                                      | truncate     | يضيف ... بعد القص، فيصبح النص أطول من الحد                          |
| cache.py                                     | get          | لا ينقل المفتاح إلى آخر الترتيب عند القراءة، فيحذف الذي استعمل للتو |
| orders.py وinventory.py وusers.py وnotify.py | لا شيء       | ملفات سليمة                                                         |

والسكربت `audit.py` يطلب من النموذج المهمة نفسها بثلاث طرق، والقاعدة في الطرق الثلاث جملة واحدة: الخطأ هو كود لا يفعل ما يقوله وصفه، وأرجع اسم الدالة أو `null`:

- **`one`:** وكيل واحد يرى الملفات العشرة في رسالة واحدة، ويرجع JSON فيه نتيجة كل ملف.
- **`sub 1 1`:** عشرة وكلاء فرعيين، كل منهم يرى ملفاً واحداً فقط ويرجع JSON بحقلين، ويعملون واحداً بعد الآخر، ثم وكيل رئيسي يرى الخلاصات العشر فقط، دون أي ملف، ويكتب خطة من ثلاثة أسطر.
- **`sub 1 2`:** الشيء نفسه، ولكن وكيلان فرعيان يعملان معاً في كل مرة، وهذا ما تسمح به إعدادات Ollama `OLLAMA_NUM_PARALLEL=2`.

ثم يأخذ السكربت `fix.py` نتائج التشغيل المتوازي، ويعطي كل خطأ وجده الوكلاء الفرعيون لوكيل منفذ يعمل في Git Worktree خاصة به وفرع خاص به، فيصلح الملف ويشغل اختبارات ذلك الملف فقط، ويعمل commit إذا نجحت، ثم يدمج الوكيل الرئيسي الفروع الناجحة في `main`. والنموذج في كل ذلك `qwen2.5:3b` بدرجة حرارة صفر على Ollama 0.40.13، والتشغيل كاملاً بالأمر:

```bash
docker run --rm --network adm-net -v "$PWD:/lab" -w /lab adm-lab:3 sh run.sh
```

والصورة `adm-lab:3` فيها Python 3.13.18 مع git، لأن `fix.py` يحتاج `git worktree`.

### وكيل واحد يقرأ الملفات العشرة: «كل شيء سليم»

بدأنا بالوكيل الواحد، والمخرج سوف يكون كما يلي:

```text
##### one agent, all ten files in one context
  BAD cache.py       expected get            got None
  BAD dates.py       expected is_leap        got None
  ok  inventory.py   expected None           got None
  ok  notify.py      expected None           got None
  ok  orders.py      expected None           got None
  BAD paging.py      expected page_count     got None
  BAD pricing.py     expected round_money    got None
  BAD text.py        expected truncate       got None
  BAD tokens.py      expected is_expired     got None
  ok  users.py       expected None           got None
RESULT one-1: bugs 0/6, false alarms 0/4, calls 1, prompt 3013 + output 201 tokens, largest single context 3013, lead context 3013, wall 141 s
```

والرد الذي كتبه النموذج، كما حفظه السكربت في `raw/`، كان سطراً واحداً من JSON يكرر لكل ملف الجملة نفسها:

```json
{"cache.py": {"function": null, "reason": "All functions match their docstrings"}, "dates.py": {"function": null, "reason": "All functions match their docstrings"}, ...}
```

في المخرج أعلاه لاحظ التالي:

- الوكيل لم يجد أي خطأ من الستة، ولم يخطئ في أي ملف سليم، لأنه قال إن كل شيء سليم، وهذه نتيجة تشبه المراجع الذي يوافق على كل طلب دمج.
- الطلب كان 3,013 توكناً فقط، وهذا صغير مقارنة بنافذة النموذج، فالمشكلة ليست أن النافذة امتلأت، وإنما أن عشر مهام في طلب واحد جعلت النموذج يجيب إجابة عامة على الكل بدل أن يفحص كل ملف.
- الرد 201 توكن لعشرة ملفات، أي عشرون توكناً لكل ملف تقريباً، وهذا لا يكفي لفحص أي شيء.

### عشرة وكلاء فرعيين: كل واحد يجد شيئاً

ثم شغلنا عشرة وكلاء فرعيين، كل منهم يرى ملفاً واحداً، واحداً بعد الآخر، والمخرج سوف يكون كما يلي:

```text
##### ten subagents, one at a time
  lead plan: For **text.py** and **users.py**, fix the function first. **text.py** needs to ensure the function returns at most `n` characters, and **users.py** should check if the role is 'customer' as specified in the docstring. ...
  BAD cache.py       expected get            got put
  BAD dates.py       expected is_leap        got add_months
  BAD inventory.py   expected None           got ship
  BAD notify.py      expected None           got notify.py::mask_phone
  BAD orders.py      expected None           got move
  ok  paging.py      expected page_count     got page_count
  BAD pricing.py     expected round_money    got line_total
  ok  text.py        expected truncate       got truncate
  BAD tokens.py      expected is_expired     got refresh
  BAD users.py       expected None           got make_user
RESULT sub1-1: bugs 2/6, false alarms 4/4, calls 11, prompt 4157 + output 531 tokens, largest single context 520, lead context 520, wall 350 s
```

في المخرج أعلاه لاحظ التالي:

- الوكلاء الفرعيون وجدوا خطأين حقيقيين من ستة، `page_count` و`truncate`، وهذا أفضل من الصفر، ولكن كل وكيل في الملفات الأربعة السليمة وجد «خطأً» أيضاً، أي أربعة إنذارات كاذبة False Alarms من أربعة.
- والسبب معروف: الوكيل الذي أعطيته ملفاً واحداً وسألته عن الخطأ فيه يفترض أن هناك خطأً، فيجده. وأسبابهم تكشف ذلك، فوكيل `inventory.py` كتب أن الدالة `ship` يجب أن تطرح `qty * qty` من المخزون، وهذا ليس له معنى.
- أكبر نافذة كانت 520 توكناً، مقابل 3,013 في الوكيل الواحد، والوكيل الرئيسي لم ير إلا الخلاصات العشر في 520 توكناً، ولكن مجموع المدخلات 4,157 توكناً، أي أكثر من الوكيل الواحد، لأن كل وكيل فرعي دفع تعليماته وقواعد المهمة من جديد.
- والوكيل الرئيسي بنى خطته على ما وصله، فبدأ بـ `users.py`، وهو ملف سليم، لأنه لا يملك ما يميز به الخلاصة الصحيحة من الخاطئة.

### ماذا رأى الوكيل الرئيسي بالضبط؟

الوكيل الرئيسي لم ير أي ملف، وكل ما وصله عشرة أسطر، سطر من كل وكيل فرعي، في طلب من 520 توكناً. وهذه أربعة منها كما وصلته:

```text
inventory.py: {"function": "ship", "reason": "... It should be self.reserved[sku] -= qty and self.stock[sku] -= qty * qty instead of ..."}
paging.py: {"function": "page_count", "reason": "It can return 0 pages for a total of 0 items, which is not what the docstring says."}
text.py: {"function": "truncate", "reason": "The truncate function does not always return at most n characters long. It can return more than n characters if the input string is shorter than n characters."}
users.py: {"function": "make_user", "reason": "The function raises ValueError for bad email and role, but does not check if the role is 'customer' which is specified in the docstring."}
```

في المخرج أعلاه لاحظ التالي:

- حتى الإجابتان الصحيحتان جاءتا بسبب خاطئ: وصف `page_count` يقول صراحة إن صفر عناصر تعني صفر صفحات، والوكيل اعتبر هذا هو الخطأ، والخطأ الحقيقي أن 41 عنصراً تعطي صفحتين بدل ثلاث. وفي `truncate` قال إن النص الأقصر من الحد يرجع أطول، والعكس هو الصحيح. أي أن اسم الدالة صحيح بالصدفة تقريباً.
- كل سطر مكتوب بالثقة نفسها، ولا يوجد في الخلاصة ما يميز الصحيح من الخاطئ، فالوكيل الرئيسي لا يستطيع أن يعرف أن سبب `users.py` مخترع، لأن الملف نفسه ليس في نافذته.
- كل وكيل فرعي استهلك بين 324 و424 توكن مدخل، منها تعليمات المهمة نفسها مكررة عشر مرات، ثم رجع بين 29 و67 توكناً، وهذا هو الشكل المثالي للخلاصة من حيث الحجم: قصيرة ومحددة، والمشكلة في المحتوى لا في الشكل.

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

### التوازي: اثنان في كل مرة

ثم أعدنا الوكلاء الفرعيين العشرة نفسها، ولكن اثنين معاً في كل مرة، والمخرج سوف يكون كما يلي:

```text
##### ten subagents, two at a time
  BAD cache.py       expected get            got put
  BAD dates.py       expected is_leap        got add_months
  BAD inventory.py   expected None           got ship
  BAD notify.py      expected None           got notify.py::render
  BAD orders.py      expected None           got move
  BAD paging.py      expected page_count     got paginate
  BAD pricing.py     expected round_money    got line_total
  ok  text.py        expected truncate       got truncate
  BAD tokens.py      expected is_expired     got issue
  ok  users.py       expected None           got None
RESULT sub2-1: bugs 1/6, false alarms 3/4, calls 11, prompt 4110 + output 515 tokens, largest single context 473, lead context 473, wall 104 s
```

في المخرج أعلاه لاحظ التالي:

- الزمن الكلي انخفض من 350 ثانية إلى 104، ولكن عندما جمعنا زمن كل استدعاء من `calls.jsonl` وجدنا أن مجموعها في التشغيل المتوازي 176 ثانية مقابل 350 في المتتالي، أي أن كل استدعاء كان أسرع بنفسه لأن المعالج كان أقل انشغالاً في تلك الدقائق. فأعدنا التشغيلين بالسكربت `timing.sh` في وقت أهدأ، فكان المتتالي 270 ثانية، منها 129 ثانية في أول استدعاء لأن النموذج كان يحمل في الذاكرة من جديد، أي قرابة 141 ثانية دون التحميل، والمتوازي 112 ثانية. فالتوازي على معالج واحد وفر قرابة 20% إلى 40% من الوقت في التشغيلين، وليس النصف، لأن الطلبين يتقاسمان الأنوية نفسها، وكل استدعاء في المتوازي أخذ وقتاً أطول من نظيره في المتتالي.
- النتائج تغيرت رغم أن درجة الحرارة صفر والبذرة نفسها: وكيل `paging.py` قال هذه المرة `paginate` بدل `page_count`، ووكيل `users.py` لم يجد شيئاً. والسبب الأرجح أن تشغيل طلبين معاً يغير ترتيب الحسابات داخل الخادم فتتغير النتائج الحدية، والمهم ألا تفترض أن التوازي يعطيك الجواب نفسه حرفياً.
- عدد الاستدعاءات والتوكنات واحد تقريباً في الطريقتين، فالتوازي غير الوقت ولم يغير الفاتورة.

![ثلاثة أعمدة للطرق: وكيل واحد بنافذة 3,013 توكناً وجد 0 من 6 ودون إنذارات كاذبة في 141 ثانية، وعشرة وكلاء فرعيين متتالين بأكبر نافذة 520 وجدوا 2 من 6 مع 4 إنذارات كاذبة من 4 في 350 ثانية، وعشرة وكلاء اثنان معاً بأكبر نافذة 473 وجدوا 1 من 6 مع 3 إنذارات كاذبة في 104 ثوان](https://arabroot.io/content/images/2026/11/subagents-parallel-03-lab.webp)

الوكيل الواحد قال إن كل شيء سليم، والوكلاء الفرعيون وجدوا أخطاء أكثر وإنذارات كاذبة أكثر، والتوازي غير الوقت لا الفاتورة

### الإصلاح في Worktrees منفصلة

بعد ذلك أعطى `fix.py` كل نتيجة من التشغيل المتوازي في الملفات الستة التي لها اختبارات لوكيل منفذ في Worktree وفرع خاص به، اثنين معاً في كل مرة، والمخرج سوف يكون كما يلي، مختصراً:

```text
$ git worktree add /work/wt-dates -b fix/dates
HEAD is now at e06670e shop with planted bugs
Preparing worktree (new branch 'fix/dates')
[cache.py] put: tests FAILED (failures=1), 328 output tokens, 137.4 s
[dates.py] add_months: tests FAILED (failures=2), 408 output tokens, 182.2 s
[paging.py] paginate: tests FAILED (failures=2), 310 output tokens, 134.1 s
[pricing.py] line_total: tests FAILED (failures=2), 390 output tokens, 141.7 s
[text.py] truncate: tests FAILED (failures=1), 306 output tokens, 79.7 s
[tokens.py] issue: tests OK, 332 output tokens, 64.2 s
workers done in 393 s
$ git worktree list
/work/repo        e06670e [main]
/work/wt-cache    e06670e [fix/cache]
/work/wt-dates    e06670e [fix/dates]
/work/wt-paging   e06670e [fix/paging]
/work/wt-pricing  e06670e [fix/pricing]
/work/wt-text     e06670e [fix/text]
/work/wt-tokens   9e7b221 [fix/tokens]
$ git merge --no-edit fix/tokens
Updating e06670e..9e7b221
Fast-forward
 shop/__pycache__/cache.cpython-313.pyc     | Bin 2197 -> 2210 bytes
 ...
 shop/tokens.py                             |   2 +-
 tests/__pycache__/test_all.cpython-313.pyc | Bin 5964 -> 5977 bytes
 8 files changed, 1 insertion(+), 1 deletion(-)
$ python -m unittest -q
Ran 11 tests in 0.003s

FAILED (failures=8)
```

في المخرج أعلاه لاحظ التالي:

- كل وكيل حصل على مجلد وفرع خاص به، والأمر `git worktree list` يبين سبعة مجلدات عمل للمستودع نفسه، كل منها على فرعه، ولم يلمس أي وكيل مجلد غيره.
- خمسة إصلاحات من ستة فشلت في اختباراتها، والسبب الأول أن أربعة منها أرسلت للدالة الخطأ: الوكيل الفرعي قال `put` فأصلح المنفذ `put`، والخطأ في `get`. والخطأ في المراجعة لا يصلحه منفذ ممتاز.
- الإصلاح الوحيد الذي نجح جاء رغم أن الوكيل الفرعي قال إن الخطأ في `issue`، فالمنفذ قرأ الملف كاملاً وأصلح المقارنة المعكوسة في `is_expired`، أي سطراً واحداً، كما يظهر في `2 +-`.
- الكود لم يدمج إلا الفرع الذي نجحت اختباراته، فبقي `main` سليماً من الإصلاحات الفاشلة، وهذه فائدة الفروع المنفصلة: الفشل يبقى في فرعه.
- والخطأ الذي وقعنا فيه نحن ظاهر في الدمج: ملفات `__pycache__` دخلت في الـ commit، لأنها كانت في المجلد عندما عملنا أول commit، ثم تغيرت عندما شغل كل وكيل الاختبارات، والأمر `git commit -a` يأخذ كل ملف متابع تغير. ضع ملف `.gitignore` قبل أن تسمح لوكيل بأن يعمل commit.

### ماذا يحدث إذا عدل وكيلان الملف نفسه؟

بقي أن نرى الحالة التي حذرنا منها في أول المقال، فكتبنا `conflict.py`: وكيلان، كل منهما في Worktree وفرع، يأخذان المهمة نفسها في الوقت نفسه، وهي إصلاح `round_money` في `pricing.py`، ثم ندمج الفرعين واحداً بعد الآخر. وفي أول تشغيل لم يحدث أي تعارض، لأن الوكيل الأول أرجع الملف كما هو دون أي تغيير، فلم يكن في فرعه شيء يدمج، والثاني أصلح الدالة وترك في الكود تعليقاً يقول `# Remove the line ...`. فأعدنا التشغيل ببذرتين أخريين، والمخرج سوف يكون كما يلي:

```text
[agent-a] tests OK
[agent-b] tests FAILED (failures=2)
$ git merge --no-edit agent-a
Updating 3109136..873e74f
Fast-forward
 shop/pricing.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
$ git merge --no-edit agent-b
Auto-merging shop/pricing.py
CONFLICT (content): Merge conflict in shop/pricing.py
Automatic merge failed; fix conflicts and then commit the result.
$ git status --short
UU shop/pricing.py
$ git diff
diff --cc shop/pricing.py
@@@ -12,7 -12,7 +12,11 @@@ def to_decimal(value)
  def round_money(amount):
      """Round to 2 decimals, half up: 10.005 -> 10.01, 10.004 -> 10.00."""
      amount = to_decimal(amount)
++<<<<<<< HEAD
 +    return amount.quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
++=======
+     return Decimal(int(amount * 100) + 50) / 100  # Fix: Use +50 to ensure correct rounding
++>>>>>>> agent-b
```

في المخرج أعلاه لاحظ التالي:

- الوكيل الأول أصلح الدالة بالطريقة الصحيحة، `quantize` مع `ROUND_HALF_UP` التي كانت مستوردة في الملف أصلاً، ونجحت اختباراته. والثاني أضاف 50 قبل القسمة، وهذا يضيف نصف ريال بدل نصف هللة، ففشل اختباران.
- الدمج الأول تقدم مباشرة Fast-forward لأن `main` لم يتغير، والدمج الثاني توقف بتعارض في السطر نفسه، والحالة `UU` تعني أن الملف معدل في الطرفين ولم يحل.
- الـ Worktrees عملت كما يجب أثناء العمل: لم يكتب وكيل فوق ملف الآخر، وكل منهما شغل اختباراته في مجلده. ولكن القرار في النهاية رجع إليك: أي السطرين تبقي؟ وهنا يساعدك أن السكربت طبع نتيجة اختبارات كل فرع، فالفرع الذي فشلت اختباراته لا يدمج أصلاً، وكان يجب ألا يعمل commit من البداية.
- والدرس الأهم أن الوكيلين عملا ضعف العمل لنتيجة واحدة، فإذا كانت المهمتان في الملف نفسه فأعطهما لوكيل واحد، أو اجعل الثاني ينتظر دمج الأول.

![فرع main في الوسط، يخرج منه فرعان agent-a وagent-b، كل منهما يعدل السطر نفسه في round_money داخل pricing.py: الأول بـ quantize وROUND_HALF_UP وعلامة صح لنجاح الاختبارات، والثاني بإضافة 50 وعلامة خطأ لفشل اختبارين، ثم الدمج الأول Fast-forward باللون الأخضر، والدمج الثاني CONFLICT باللون الأحمر مع الحالة UU](https://arabroot.io/content/images/2026/11/subagents-parallel-04-conflict.webp)

وكيلان والمهمة نفسها في الملف نفسه: الـ Worktree تحمي العمل أثناءه، والتعارض ينتظرك عند الدمج

## كيف يتحقق الوكيل الرئيسي من نتيجة الوكيل الفرعي؟

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

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

والطريقة الأولى وحدها كانت كافية لتكشف أن وكيل `notify.py` رجع باسم مثل `notify.py::render`، وهو ليس اسم دالة أصلاً، وأن وكيل `tokens.py` سمى `issue`، وهي دالة لا يوجد فيها ما يخالف وصفها. أما الطريقة الثانية فكانت ستكشف الإنذارات الكاذبة الأربعة، لأن أي اختبار يكتبه الوكيل عن `ship` أو `move` سوف ينجح على الكود الحالي.

## العمل في الخلفية: ماذا تفعل أنت أثناء عمل الوكلاء؟

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

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

## متى تستعمل وكيلاً فرعياً، ومتى لا؟

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

## كيف تكتب وكيلاً فرعياً جيداً؟

من المختبر ومن توثيق الأدوات يمكن أن نجمع ما يجعل الوكيل الفرعي مفيداً في خمس نقاط، وكلها تعود إلى سؤال واحد: ماذا يرى، وماذا يرجع؟

1. **مهمة واحدة واضحة:** «راجع ملفاً واحداً وقل أي دالة تخالف وصفها» أفضل من «راجع المشروع وقل ما فيه من مشاكل»، لأن الأولى لها جواب يمكن فحصه، والثانية لها مئة جواب كلها صحيحة جزئياً.
2. **شكل نتيجة محدد وقصير:** JSON بحقلين أو ثلاثة، أو قائمة بمسار ورقم سطر، لأن النتيجة هي ما يدخل نافذة الوكيل الرئيسي، والوكيل الرئيسي سوف يقرؤها في كل دورة بعدها.
3. **أقل الأدوات الممكنة:** وكيل البحث لا يحتاج الكتابة، ووكيل المراجعة لا يحتاج الشبكة، وكل أداة تحذفها تحذف نوعاً من الأخطاء ومن الأضرار، وتحذف أيضاً تعريفها من كل طلب.
4. **نموذج يناسب المهمة:** القراءة والبحث وتلخيص الملفات مهام يقوم بها نموذج أرخص بشكل جيد، وتوثيق Claude Code يسمح بتحديد النموذج لكل وكيل بالحقل `model`، وصفحة التكاليف تنصح باستعمال Sonnet للزملاء في فرق الوكلاء بدل النموذج الأغلى.
5. **وصف يقول متى يستعمل:** الوكيل الرئيسي يختار الوكيل الفرعي من وصفه، فاكتب الوصف كتعليمات استعمال: متى، وماذا تعطيه، وماذا يرجع.

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

- **وصف مهمة ناقص:** الوكيل الفرعي لا يرى محادثتك، فإذا قلت للوكيل الرئيسي في أول الجلسة «تجاهل مجلد `legacy/`» ولم يكتبها في وصف المهمة، فإن الوكيل الفرعي سوف يقرأ المجلد ويرجع بنتائج منه.
- **الثقة بالخلاصة دون دليل:** الوكيل الرئيسي يرى الخلاصة فقط، فإذا أخطأ الوكيل الفرعي فإن الخطأ يصل مختصراً وواثقاً. اطلب في النتيجة ما يثبتها، مثل المسار ورقم السطر أو مخرج الاختبار، وافحصه في الكود.
- **الكتابة بالتوازي في مجلد واحد:** وكيلان يعدلان مجلد العمل نفسه في الوقت نفسه، فيقرأ أحدهما ملفاً نصف معدل، أو يفشل اختباره بسبب تعديل الآخر. كل كاتب في Worktree خاصة به.
- **توقع أن التوازي مجاني:** عشرة وكلاء معاً تعني عشرة أضعاف التعليمات والأدوات في الطلبات، ونموذجك المحلي لا يصبح أسرع لأنك أرسلت له طلبين معاً، والمزود يطبق حدود المعدل Rate Limits على حسابك كله.
- **تقسيم الملف الواحد على وكيلين:** الـ Worktree تؤجل التعارض إلى وقت الدمج ولا تلغيه. قسم بالملفات أو بالوحدات، وإذا كانت المهمتان في الملف نفسه فأعطهما لوكيل واحد أو بالترتيب.
- **ترك الـ Worktrees والفروع بعد الانتهاء:** كل Worktree مجلد كامل من ملفات المشروع على القرص، وكل فرع قديم يربك من يأتي بعدك. احذفها بالأمر `git worktree remove` بعد الدمج، أو استعمل خيار الأداة الذي يحذفها تلقائياً.

## قائمة تحقق

- هل المهمة قراءة فقط؟ إذا نعم فالوكلاء الفرعيون بالتوازي آمنون نسبياً.
- هل وصف المهمة يحمل كل الشروط التي قلتها للوكيل الرئيسي؟
- هل شكل النتيجة محدد وقصير، ومعه دليل يمكن فحصه؟
- هل أدوات الوكيل الفرعي أقل ما يمكن؟
- إذا كانت المهمة كتابة: هل لكل وكيل Worktree وفرع، وهل الملفات مقسمة بحيث لا يلمس وكيلان الملف نفسه؟
- هل الاختبارات تعمل في كل Worktree قبل أن يعمل الوكيل commit؟
- هل تعرف عدد الوكلاء الذين يعملون معاً، وحدود المعدل عند المزود أو قدرة جهازك؟
- هل تحذف الـ Worktrees والفروع بعد الدمج؟

## تدريب عملي

1. في `audit.py` غير قاعدة الوكيل الفرعي لتقول «إذا لم تكن متأكداً فأرجع null، والإنذار الكاذب أسوأ من أن تفوت خطأً»، وأعد التشغيل: كم إنذاراً كاذباً بقي، وكم خطأً حقيقياً ضاع؟
2. أعط كل وكيل فرعي اختبارات ملفه أيضاً واسمح له أن يشغلها، وقارن عدد الأخطاء التي يجدها بالتشغيل الأول.
3. في `fix.py` أضف ملف `.gitignore` فيه `__pycache__/` قبل أول commit، واجعل الـ commit يحدث فقط إذا نجحت الاختبارات، ثم أعد تشغيل `conflict.py`: ماذا يتغير عند الدمج؟

## الخلاصة

- الوكيل الفرعي حلقة وكيل جديدة بنافذة نظيفة، يراها الوكيل الرئيسي كأداة: وصف مهمة يدخل، ورسالة واحدة تخرج، والفاتورة تجمع توكنات النافذتين.
- وصف المهمة هو كل ما يعرفه الوكيل الفرعي، فكل شرط لم يكتب فيه غير موجود بالنسبة له.
- القراءة بالتوازي آمنة نسبياً، والكتابة بالتوازي تحتاج Worktree وفرعاً لكل وكيل، وتقسيماً بالملفات، لأن التعارض يؤجل إلى الدمج ولا يختفي.
- Claude Code يعرف الوكلاء الفرعيين في ملفات Markdown ويعزلهم بـ `isolation: worktree`، وCodex في ملفات TOML وفي مهام سحابية، وCursor في Worktrees محلية ووكلاء سحابيين، وCopilot في وكيل سحابي لكل مهمة.
- في المختبر قال الوكيل الواحد إن الملفات العشرة سليمة فلم يجد شيئاً، ووجد الوكلاء الفرعيون خطأين من ستة مع إنذار كاذب في كل ملف سليم، والتوازي اختصر الوقت ولم يغير التوكنات.
- خمسة إصلاحات من ستة فشلت لأن الوكيل الفرعي سمى الدالة الخطأ، والفرع الوحيد الذي دمج هو الذي نجحت اختباراته، ووكيلان على الملف نفسه أنتجا تعارضاً في السطر نفسه.

وقد شرحنا الـ Worktrees والفروع وطريقة الرجوع الآمن بالتفصيل في مقال Git مع الوكلاء، وفي المقالات التالية من هذه المرحلة بإذن الله نقارن أطر التنسيق التي تبني الوكلاء الفرعيين لك، ثم نرى فريق الوكلاء الذي يتناقش، ثم نحسب التكلفة:

[![](https://arabroot.io/content/images/2026/11/git-hygiene-agents-cover-cover.webp)دليلGit مع وكلاء البرمجة: فروع وWorktrees ورجوع آمنفرع وWorktree لكل مهمة، وcommit صغير برسالة تقول من كتبه، وفحص لا يتجاوزه الوكيل، وطريق معروف للرجوع، مع مختبر حقيقي فيه خطاف لم يعمل وcommit أوقف المشروع وجده git bisect.](https://arabroot.io/articles/git-%D9%85%D8%B9-%D9%88%D9%83%D9%84%D8%A7%D8%A1-%D8%A7%D9%84%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D9%81%D8%B1%D9%88%D8%B9-%D9%88worktrees-%D9%88%D8%B1%D8%AC%D9%88%D8%B9-%D8%A7%D9%85%D9%86/)[![](https://arabroot.io/content/images/2026/11/multi-agent-concepts-cover-cover.webp)دليلتعدد الوكلاء Multi-agent: المخطط والمنفذ والمراجعمتى يحتاج العمل أكثر من وكيل، وما الذي يضيع عند التسليم بين المخطط والمنفذ والمراجع، مع تجربة على نموذج محلي تقارن وكيلاً واحداً بفريق على المهمة نفسها.](https://arabroot.io/articles/%D8%AA%D8%B9%D8%AF%D8%AF-%D8%A7%D9%84%D9%88%D9%83%D9%84%D8%A7%D8%A1-multi-agent-%D8%A7%D9%84%D9%85%D8%AE%D8%B7%D8%B7-%D9%88%D8%A7%D9%84%D9%85%D9%86%D9%81%D8%B0-%D9%88%D8%A7%D9%84%D9%85%D8%B1%D8%A7%D8%AC%D8%B9/)[![](https://arabroot.io/content/images/2026/11/multi-agent-frameworks-cover-cover.webp)دليلأطر تنسيق الوكلاء Agent Frameworks: LangGraph وCrewAI وAG2خمسة أطر لتعدد الوكلاء على مهمة واحدة ونموذج محلي واحد، مع وسيط يسجل كل طلب يرسله الإطار، لترى التعليمات المخفية والاستدعاءات وأين وقع الخطأ في كل منها.](https://arabroot.io/articles/%D8%A7%D8%B7%D8%B1-%D8%AA%D9%86%D8%B3%D9%8A%D9%82-%D8%A7%D9%84%D9%88%D9%83%D9%84%D8%A7%D8%A1-agent-frameworks-langgraph-%D9%88crewai-%D9%88ag2/)[![](https://arabroot.io/content/images/2026/11/agent-team-discussion-cover-cover.webp)دليلفريق وكلاء يتناقش Multi-agent Debate: هل يتحسن الجواب؟ما تقوله الأبحاث عن النقاش بين الوكلاء، وكيف بنت ChatDev وMetaGPT ومحادثات AutoGen فرقها، وتجربة على نموذج محلي تقارن النقاش والتصويت والناقد والحكم على أسئلة معروفة الجواب.](https://arabroot.io/articles/%D9%81%D8%B1%D9%8A%D9%82-%D9%88%D9%83%D9%84%D8%A7%D8%A1-%D9%8A%D8%AA%D9%86%D8%A7%D9%82%D8%B4-multi-agent-debate-%D9%87%D9%84-%D9%8A%D8%AA%D8%AD%D8%B3%D9%86-%D8%A7%D9%84%D8%AC%D9%88%D8%A7%D8%A8/)[![](https://arabroot.io/content/images/2026/11/multi-agent-cost-cover-cover.webp)دليلمتى يصبح تعدد الوكلاء Multi-agent أغلى وأبطأ من وكيل واحد؟من أين تأتي التوكنات الإضافية في فرق الوكلاء، ولماذا لا يختصر التوازي الوقت دائماً، مع أرقام حقيقية من مختبرات المرحلة محولة إلى تكلفة سنة بأسعار Anthropic وOpenAI وGoogle الرسمية.](https://arabroot.io/articles/%D9%85%D8%AA%D9%89-%D9%8A%D8%B5%D8%A8%D8%AD-%D8%AA%D8%B9%D8%AF%D8%AF-%D8%A7%D9%84%D9%88%D9%83%D9%84%D8%A7%D8%A1-multi-agent-%D8%A7%D8%BA%D9%84%D9%89-%D9%88%D8%A7%D8%A8%D8%B7%D8%A7-%D9%85%D9%86-%D9%88%D9%83%D9%8A%D9%84-%D9%88%D8%A7%D8%AD%D8%AF/)

## سجل التحديثات

- 20 نوفمبر 2026: كتابة المقال، وتشغيل مقارنة الوكيل الواحد بعشرة وكلاء فرعيين، والإصلاح في Git Worktrees والتعارض بين وكيلين، على Ollama 0.40.13 بنموذج qwen2.5:3b وgit 2.47.3.