وضع التعاون بين الوكلاء الفرعيين

فهم الوكلاء الفرعيين في Claude Code واستخدامهم — الاستكشاف المتوازي، والمهام الخلفية، والتنفيذ المعزول

تحتاج مفتاح API؟ أنشئ حسابًا ←·نقاط النهاية وعناوين Base URL ←

وضع التعاون بين الوكلاء الفرعيين¶

تخيّل: أن تطلب من Claude مساعدتك في إعادة هيكلة وحدة كبيرة، لكن قبل إعادة الهيكلة، تحتاج إلى أن يحدد أولًا ثلاثة أمور — ما واجهات API الموجودة، وكيف يبدو مخطط قاعدة البيانات، وما مستوى تغطية الاختبارات. في الوضع العادي، لا يستطيع Claude التحقق منها إلا واحدًا تلو الآخر بالتتابع. لكن ماذا لو أمكنه إرسال ثلاث «نسخ» للاستقصاء في الوقت نفسه؟

هذا هو سحر الوكلاء الفرعيين.

ما الوكلاء الفرعيون؟¶

مفهوم أداة الوكيل¶

الوكيل الفرعي أداة خاصة في Claude Code تتيح للجلسة الرئيسية إنشاء نسخ مستقلة من Claude لتنفيذ مهام محددة. يمكنك تخيّله على أنه «Claude استعان بمساعد».

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

الفروق بين الوكلاء الفرعيين والجلسة الرئيسية¶

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

مزايا نافذة السياق المستقلة¶

لماذا يُعدّ السياق المستقل مهمًا إلى هذا الحد؟ إليك مثالًا عمليًا:

لنفترض أنك تحتاج إلى Claude لتحليل مشروع يضم 200 ملف. إذا قرأت الملفات واحدًا تلو الآخر في الجلسة الرئيسية، بمعدل 200 سطر لكل ملف، فسيشغل محتوى الملفات وحده 40,000 سطر من السياق. أضف إلى ذلك عملية تحليل Claude، وستملأ السياق سريعًا.

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

أنواع الوكلاء الفرعيين المدمجة¶

الوكلاء الفرعيون في Claude Code ليسوا في الواقع «أنواعًا» ثابتة، بل تُنشئهم الجلسة الرئيسية بمرونة بحسب طبيعة المهمة. غير أن الوكلاء الفرعيين، عمليًا، يضطلعون عادةً بالأدوار التالية:

Explore (البحث في الشيفرة والاستكشاف)¶

هذه هي حالة الاستخدام الأكثر شيوعًا للوكلاء الفرعيين. عندما يحتاج Claude إلى فهم جانب معين من المشروع، يشغّل وكيلًا فرعيًا من نوع Explore:

القدرات:

• قراءة الملفات (Read)
• البحث في الشيفرة (Grep، Glob)
• عرض بنية الدليل
• تحليل تبعيات الشيفرة

القيود:

• يُمنح عادةً أدوات للقراءة فقط
• لا يمكنه تعديل الملفات
• لا يمكنه تنفيذ الأوامر

السيناريوهات النموذجية:

Analyze public interfaces for all services in the src/services/ directory
Find all files that reference UserService
Understand the workflow of the authentication middleware

Plan (تصميم البنية والتخطيط)¶

الوكلاء الفرعيون المستخدمون لصياغة الخطط أو حلول التصميم:

القدرات:

• جميع قدرات Explore
• البحث على الويب (الوثائق، أفضل الممارسات)
• إنشاء وثائق حلول مفصّلة

السيناريوهات النموذجية:

Design a cache layer architecture
Evaluate feasibility of migrating from REST to GraphQL
Formulate a database sharding strategy

General-Purpose (المهام العامة)¶

الوكلاء الفرعيون الذين يتولون مهام تنفيذ محددة، مع وصول كامل إلى الأدوات:

القدرات:

• قراءة الملفات وكتابتها
• تنفيذ الأوامر
• تشغيل الاختبارات
• تثبيت التبعيات

السيناريوهات النموذجية:

Run the full test suite in the background
Generate API documentation
Execute code formatting

متى تستخدم الوكلاء الفرعيين¶

السيناريو 1: البحث في الشيفرة وفهمها¶

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

I just took over this project. Please help me understand its architecture comprehensively:
1. Use a subagent to analyze the backend directory structure and core modules
2. Use a subagent to analyze the frontend component tree and state management
3. Use a subagent to analyze the database schema and entity relationships
Then synthesize information from all three areas and give me a project architecture overview.

قد يشغّل Claude ثلاثة وكلاء فرعيين لتنفيذ هذه المهام على التوازي، ثم يجمع تقاريرها.

السيناريو 2: بحث متوازٍ في حلول متعددة¶

عندما تحتاج إلى مقارنة عدة حلول تقنية، تكون قدرة الوكلاء الفرعيين على العمل بالتوازي مفيدة جدًا:

I need to choose a message queue for the project. Please research the following solutions separately:
1. Redis Streams — check if our existing Redis configuration supports it
2. RabbitMQ — evaluate the cost of introducing new dependencies
3. Using PostgreSQL's LISTEN/NOTIFY directly
For each solution, analyze the pros and cons and compatibility with our project.

السيناريو 3: تشغيل المهام الطويلة في الخلفية¶

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

Please run the full test suite in the background while I continue working on other things.
Tell me the results when the tests are done.

سيشغّل Claude وكيلًا فرعيًا في الخلفية لتنفيذ الاختبارات. يمكنك مواصلة التحدث مع الجلسة الرئيسية دون انتظار.

السيناريو 4: عزل العمليات عالية المخاطر¶

عندما تحتاج إلى تنفيذ عمليات قد تنطوي على مخاطر، يمكنك استخدام وكيل فرعي للعزل:

Please try the following operations using a subagent:
1. Switch to a temporary branch
2. Try upgrading React to 19.x
3. Run the build and see how many compatibility errors there are
4. Send me the error list
Do not operate on the main branch.

دليل عملي للوكلاء الفرعيين¶

المثال 1: استخدام الوكلاء الفرعيين لفهم قاعدة شيفرة غير مألوفة¶

لنفترض أن هذا يومك الأول في مشروع Python متوسط الحجم (نحو 50 ملفًا مصدريًا)، وأنك بحاجة إلى فهم بنيته بسرعة.

الـ prompt الخاص بك:

It's my first day on this project. Please help me quickly build an understanding of it.
Use subagents to analyze the following areas in parallel:

1. Project structure and entry points — scan directory structure, find main entry, routing definitions, config files
2. Data models — analyze all model files and draw entity relationships
3. Business logic — analyze the services directory and understand core business workflows
4. External dependencies — analyze requirements.txt and actual imports to identify key dependencies

Finally, synthesize all the information into a project overview of no more than 500 words.

عملية تنفيذ Claude:

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

Launching 4 subagents for parallel analysis...

[Subagent 1] Analyzing project structure...

  - Scanned 52 Python files
  - Found entry point: main.py → FastAPI app
  - Route definitions in routers/ directory (8 routing modules)
  - Config: config.py + .env

[Subagent 2] Analyzing data models...

  - Found 12 SQLAlchemy models
  - Core entities: User, Organization, Project, Task, Comment
  - Key relationships: User ← many-to-many → Organization, Project → has-many → Task

[Subagent 3] Analyzing business logic...

  - 9 service files
  - Core workflows: user management, project management, task assignment, notification system
  - Async task processing using Celery

[Subagent 4] Analyzing external dependencies...

  - 32 direct dependencies
  - Key dependencies: FastAPI, SQLAlchemy, Celery, Redis, Alembic
  - Found 2 unused dependencies (requests, beautifulsoup4)

في النهاية، يجمع Claude نتائج الوكلاء الفرعيين الأربعة ويعطيك نظرة عامة منظمة على المشروع.

المثال 2: تشغيل عدة وكلاء فرعيين بالتوازي لمقارنة الحلول¶

أنت تفكر في كيفية تنفيذ إشعارات فورية وترغب في مقارنة عدة حلول:

I need to add real-time notification functionality to the project. Please help me evaluate the following three solutions in parallel:

Solution A: WebSocket (using FastAPI's built-in WebSocket support)
Solution B: Server-Sent Events (SSE)
Solution C: Polling

For each solution, please analyze:
1. Compatibility with our existing architecture (check existing code)
2. Implementation complexity (approximately how many files need changes)
3. Performance and scalability
4. Client compatibility

Then give me a comparison table and your recommendation.

قد تكون نتائج المقارنة لدى Claude كما يلي:

All three subagents have completed analysis. Summary comparison:

| Evaluation Dimension | WebSocket | SSE | Polling |
|----------|-----------|-----|------|
| Architecture Compatibility | Need to add WebSocket routes | Can reuse existing HTTP routes | Fully compatible |
| Implementation Complexity | High (~8 files) | Medium (~4 files) | Low (~2 files) |
| Real-time Capability | Best (full duplex) | Good (server push) | Average (depends on polling interval) |
| Scalability | Needs WebSocket load balancing | Can use CDN | Simplest |
| Celery Integration | Needs additional message bridge | Can directly consume Celery events | Poll database |

**Recommendation**: Considering you're already using Celery + Redis, SSE is the best choice.
It can directly subscribe to Redis channels to get Celery events, with moderate implementation complexity,
and doesn't require additional infrastructure.

المثال 3: تشغيل الاختبارات باستخدام وكيل فرعي في الخلفية¶

أنت تعدّل الشيفرة وترغب في معرفة نتائج الاختبار في الوقت نفسه:

Please run pytest in the background and run the full test suite. I'll continue modifying code. Tell me when it's done.

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

Background tests completed. Results:

- Total: 247 tests
- Passed: 241
- Failed: 4
- Skipped: 2

Failed tests:
1. test_order_service.py::test_calculate_total_with_discount
   AssertionError: 99.99 != 100.0
2. test_user_service.py::test_create_user_duplicate_email
   IntegrityError: Test database not properly cleaned up
3. ...

Would you like me to analyze these failing tests?

تكوين الوكلاء الفرعيين¶

الوكلاء الفرعيون المخصصون: اختيار النموذج والأدوات في ملف¶

حتى 2026-10-15، وفقًا لوثائق Claude Code، فإن الوكيل الفرعي المخصص هو ملف Markdown يحتوي على YAML frontmatter. ضعه في .claude/agents/ (هذا المشروع فقط) أو ~/.claude/agents/ (جميع مشاريعك)، أو ببساطة اطلب من Claude كتابته لك. الحقلان name وdescription فقط مطلوبان:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

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

يقبل model الأسماء المستعارة sonnet / opus / haiku / fable، أو معرّف نموذج كامل (مثل claude-opus-5-5 أو claude-sonnet-5)، أو inherit لاستخدام نموذج المحادثة الرئيسية. يختار Claude Code نموذج الوكيل الفرعي بهذا الترتيب (الأسبق يفوز):

1. المعامل model الممرَّر لذلك الاستدعاء تحديدًا
2. حقل model في تعريف الوكيل الفرعي
3. متغير البيئة CLAUDE_CODE_SUBAGENT_MODEL
4. النموذج الحالي للمحادثة الرئيسية

للتحقق من النموذج الذي يعمل عليه الوكيل الفرعي فعليًا، شغّل /tasks (يتطلب Claude Code v2.1.242 أو أحدث). يُعدّ ضبط الوكلاء الفرعيين من نوع البحث على haiku وترك المحادثة الرئيسية لنموذج أقوى طريقة شائعة لإبقاء الاستخدام تحت السيطرة.

توجيه سلوك الوكلاء الفرعيين عبر CLAUDE.md¶

بالإضافة إلى ملفات الوكلاء الفرعيين أعلاه، يمكنك استخدام CLAUDE.md لتوجيه Claude حول متى وكيف يستخدم الوكلاء الفرعيين:

## Subagent Usage Guidelines

### When to Use Subagents

- Tasks analyzing more than 10 files should use subagents
- When comparing multiple solutions, launch independent subagents for each
- Running tests should be executed in background subagents

### Subagent Task Description Template
When launching subagents, the task description should include:
1. Clear objectives (what to do)
2. Scope limitations (what not to do)
3. Output format (what kind of results to return)

### Subagent Result Handling
Subagent results must include:

- Analysis summary (no more than 200 words)
- Key findings list
- Related file paths
- Potential risks or issues

فهم الأدوات المتاحة للوكلاء الفرعيين¶

تعتمد الأدوات التي يمكن للوكيل الفرعي استخدامها على التفويض من الجلسة الرئيسية. عمليًا:

• مهام القراءة فقط: عادةً تُمنح أدوات بحث فقط مثل Read وGrep وGlob
• مهام التنفيذ: تُمنح أدوات كتابة مثل Bash وWrite وEdit
• مهام الشبكة: تُمنح أدوات شبكة مثل WebSearch وWebFetch

يمكنك الإشارة إلى نطاق الأدوات عبر اللغة الطبيعية:

Please use a subagent to analyze (read-only) the relationships of all models in the src/models/ directory.

بإضافة إشارة «للقراءة فقط»، يميل Claude إلى إنشاء وكيل فرعي بقدرات بحث وقراءة فقط.

التنفيذ في الخلفية¶

يمكن للوكلاء الفرعيين العمل في الخلفية دون حجب تفاعلك مع الجلسة الرئيسية. عندما تقول «في الخلفية...» أو «بشكل غير متزامن...»، سيستخدم Claude المعامل run_in_background:

Please help me with two things in the background:
1. Run the complete lint check
2. Check all dependencies for known security vulnerabilities
I'll continue modifying code and let me know when done.

عند اكتمال وكيل فرعي يعمل في الخلفية، يخطر النظام Claude، الذي يمرر النتائج إليك بعد ذلك.

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

1. امنح الوكلاء الفرعيين أوصاف مهام واضحة¶

سياق الوكيل الفرعي جديد تمامًا — فهو لا يعرف ما ناقشته مع الجلسة الرئيسية سابقًا. لذلك يجب أن تكون أوصاف المهام مكتفية بذاتها:

ممارسة سيئة:

Use a subagent to check the issue mentioned earlier.

(لا يعرف الوكيل الفرعي ما المقصود بـ «المشكلة المذكورة سابقًا»)

ممارسة جيدة:

Use a subagent to check whether the process_refund() method in src/services/payment_service.py correctly handles concurrent refund requests.
Need to pay attention to database transaction isolation levels and use of optimistic locking.

2. استخدم وكلاء فرعيين متوازيين لتحسين الكفاءة¶

عندما لا تعتمد مهام متعددة على بعضها بعضًا، فدعها تُنفَّذ بالتوازي:

Please execute the following tasks in parallel:
1. [Subagent A] Analyze all API call points in the frontend code
2. [Subagent B] Analyze backend API endpoints and parameter definitions
3. [Subagent C] Check if API documentation is consistent with actual interfaces

After all three tasks are complete, summarize the API inconsistencies.

3. لا تفرط في استخدام الوكلاء الفرعيين¶

الوكلاء الفرعيون ليسوا حلًا سحريًا. يكون التعامل مع السيناريوهات التالية مباشرةً في الجلسة الرئيسية أكثر كفاءة:

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

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

4. افهم آلية تسليم نتائج الوكيل الفرعي¶

عندما يكمل الوكيل الفرعي مهمته، تُعاد نتائجه إلى الجلسة الرئيسية بصيغة ملخّصة. وهذا يعني:

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

The subagent told me there's an issue on line 127 of payment_service.py.
Please show me lines 120-140 of that file.

5. استخدم الوكلاء الفرعيين في العمليات «الاستكشافية»¶

لست متأكدًا مما إذا كان نهج معيّن قابلًا للتنفيذ؟ استخدم وكيلًا فرعيًا للتجريب بدلًا من المخاطرة على الفرع الرئيسي:

Please use a subagent to run an experiment:
1. Create a temporary directory /tmp/experiment
2. Copy src/models/user.py into it
3. Try replacing SQLAlchemy's declarative models with dataclasses
4. See what problems arise

Don't touch any project files.

متقدم: دمج الوكلاء الفرعيين مع ميزات أخرى¶

الوكلاء الفرعيون + وضع التخطيط¶

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

(In Plan mode)
Please use subagents to help me research the following questions, then formulate a migration plan based on the research results:
1. List of all current REST API endpoints and their call frequencies
2. Which endpoints already have equivalent GraphQL implementations
3. How much the client code depends on REST APIs

الوكلاء الفرعيون + أدوات MCP¶

إذا كنت قد أعددت خوادم MCP (مثل أدوات استعلام قواعد البيانات)، فيمكن للوكلاء الفرعيين استخدامها أيضًا:

Please use a subagent to connect to the database and analyze the following:
1. Data volume for each table
2. Top 10 slow queries
3. Missing indexes
Use the database MCP tool to execute queries.

الوكلاء الفرعيون + Hooks¶

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

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "curl -X POST https://hooks.slack.com/... -d '{\"text\": \"$MESSAGE\"}'"
          }
        ]
      }
    ]
  }
}

الأسئلة الشائعة¶

س: هل يمكن للوكلاء الفرعيين رؤية سجل محادثتي مع الجلسة الرئيسية؟

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

س: هل يمكن للوكلاء الفرعيين إطلاق «وكلاء فرعيين من مستوى أدنى»؟

ج: نعم، لكن لا يُوصى بالتداخل العميق جدًا. عادةً تكفي طبقة واحدة من الوكلاء الفرعيين.

س: هل يمكن لعدة وكلاء فرعيين التواصل مع بعضهم بعضًا؟

ج: لا، ليس مباشرةً. إذا كنت تحتاج إلى أن يعتمد الوكيل الفرعي B على نتائج الوكيل الفرعي A، فلا يمكنك إلا انتظار اكتمال A، ثم تمرر الجلسة الرئيسية النتائج إلى B.

س: هل يستهلك الوكلاء الفرعيون حصة API إضافية؟

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

س: كيف أعرف ما الذي يفعله الوكيل الفرعي؟

ج: يعرض Claude حالة تنفيذ الوكلاء الفرعيين في الجلسة الرئيسية. يمكنك رؤية الوكلاء الفرعيين الذين أطلقهم، وما يفعله كل وكيل فرعي، وما إذا كان قد أكمل عمله.

المؤسسات ←