حالت همکاری زیرعامل‌ها

درک و استفاده از زیرعامل‌های Claude Code — کاوش موازی، کارهای پس‌زمینه، اجرای جداگانه

به کلید API نیاز دارید؟ ثبت‌نام ←·نقاط پایانی و Base URL ←

حالت همکاری زیرعامل‌ها¶

تصور کنید: از Claude می‌خواهید به شما در بازآرایی یک ماژول بزرگ کمک کند، اما پیش از بازآرایی لازم است ابتدا سه چیز را مشخص کند — چه رابط‌های API وجود دارند، شِمای پایگاه داده چگونه است و پوشش تست در چه وضعیتی قرار دارد. در حالت عادی، Claude فقط می‌تواند این موارد را یکی‌یکی و به‌صورت متوالی بررسی کند. اما چه می‌شد اگر می‌توانست سه «کلون» را برای بررسی هم‌زمان بفرستد؟

این جذابیت زیرعامل‌هاست.

زیرعامل‌ها چه هستند¶

مفهوم ابزار عامل¶

زیرعامل ابزاری ویژه در Claude Code است که به نشست اصلی اجازه می‌دهد نمونه‌های مستقل Claude را برای اجرای کارهای مشخص ایجاد کند. می‌توانید آن را این‌طور در نظر بگیرید که «Claude یک دستیار استخدام کرده است».

Claude در نشست اصلی نقش مدیر پروژه را دارد و مسئول هماهنگی کلی است. وقتی با زیرکارهایی روبه‌رو می‌شود که نیاز به بررسی عمیق دارند، می‌تواند یک زیرعامل را برای رسیدگی اختصاصی به آن‌ها راه‌اندازی کند و در همان حال به کارهای دیگر نیز رسیدگی کند.

تفاوت‌های زیرعامل‌ها با نشست اصلی¶

مهم‌ترین تفاوت، پنجره زمینه مستقل است. زیرعامل‌ها فضای زمینه خودشان را دارند؛ فرایند کاوش آن‌ها زمینه نشست اصلی را گسترش نمی‌دهد. تنها نتایج نهایی به نشست اصلی بازگردانده می‌شوند — مانند اینکه کسی را برای تحقیق به سفر کاری بفرستید؛ وقتی برمی‌گردد، فقط کافی است گزارشی به شما بدهد، نه اینکه تمام فرایند تحقیق را دوباره بازگو کند.

مزایای پنجره زمینه مستقل¶

چرا زمینه مستقل این‌قدر مهم است؟ یک مثال عملی را در نظر بگیرید:

فرض کنید از Claude می‌خواهید پروژه‌ای با 200 فایل را تحلیل کند. اگر در نشست اصلی فایل‌ها را یکی‌یکی بخوانید و هر فایل به‌طور میانگین 200 خط داشته باشد، فقط محتوای فایل‌ها 40,000 خط زمینه را اشغال می‌کند. فرایند تحلیل Claude را هم اضافه کنید؛ به‌سرعت زمینه پر می‌شود.

با زیرعامل‌ها ماجرا فرق می‌کند. زیرعامل این فایل‌ها را در زمینه خودش می‌خواند و تحلیل می‌کند و در پایان فقط چند صد خط گزارش تحلیل را برمی‌گرداند. زمینه نشست اصلی تقریباً افزایش نمی‌یابد و شما همچنان فضای زیادی برای ادامه کارهای بعدی دارید.

انواع زیرعامل‌های توکار¶

زیرعامل‌ها در Claude Code در واقع «نوع‌های» ثابت نیستند، بلکه نشست اصلی آن‌ها را بر اساس ماهیت وظیفه به‌شکل انعطاف‌پذیر ایجاد می‌کند. با این حال، در عمل، زیرعامل‌ها معمولاً نقش‌های زیر را می‌گیرند:

کاوش (جست‌وجو و بررسی کد)¶

این رایج‌ترین مورد استفاده زیرعامل‌هاست. وقتی Claude نیاز دارد جنبه خاصی از یک پروژه را درک کند، یک زیرعامل کاوش راه‌اندازی می‌کند:

قابلیت‌ها:

• خواندن فایل‌ها (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

برنامه‌ریزی (طراحی معماری و برنامه‌ریزی)¶

زیرعامل‌هایی که برای تدوین برنامه‌ها یا طراحی راهکارها استفاده می‌شوند:

قابلیت‌ها:

• همه قابلیت‌های کاوش
• جست‌وجوی وب (مستندات، بهترین شیوه‌ها)
• تولید اسناد تفصیلی راهکار

سناریوهای معمول:

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

همه‌منظوره (وظایف همه‌منظوره)¶

زیرعامل‌هایی که وظایف اجرایی مشخص را با دسترسی کامل به ابزارها انجام می‌دهند:

قابلیت‌ها:

• خواندن و نوشتن فایل‌ها
• اجرای دستورها
• اجرای آزمون‌ها
• نصب وابستگی‌ها

سناریوهای معمول:

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 با frontmatter YAML است. آن را در .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.

با افزودن اشاره «read-only»، Claude معمولاً زیرعاملی می‌سازد که فقط قابلیت جست‌وجو و خواندن دارد.

اجرا در پس‌زمینه¶

زیرعامل‌ها می‌توانند در پس‌زمینه اجرا شوند بدون این‌که تعامل شما با نشست اصلی را مسدود کنند. وقتی می‌گویید «in the background...» یا «asynchronously...»، 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.

پیشرفته: ترکیب زیرعامل‌ها با سایر قابلیت‌ها¶

زیرعامل‌ها + حالت Plan¶

می‌توانید از زیرعامل‌ها در حالت Plan نیز استفاده کنید. این ترکیب قدرتمندی است — از زیرعامل‌ها برای پژوهش عمیق در مرحله برنامه‌ریزی استفاده کنید:

(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 اضافی مصرف می‌کنند؟

پاسخ: بله. زیرعامل‌ها از پنجره‌های زمینه مستقل استفاده می‌کنند و ورودی و خروجی هر زیرعامل توکن مصرف می‌کند. اما چون زمینه زیرعامل معمولاً کوچک‌تر است (فقط شامل وظایف مشخص)، مصرف کل اغلب کمتر از انجام همان کار در نشست اصلی است.

پرسش: چگونه بفهمم زیرعامل چه کاری انجام می‌دهد؟

پاسخ: Claude وضعیت اجرای زیرعامل را در نشست اصلی نمایش می‌دهد. می‌توانید ببینید کدام زیرعامل‌ها را راه‌اندازی کرده، هر زیرعامل چه کاری انجام می‌دهد و آیا کار را کامل کرده است یا نه.

سازمانی ←