# Dynamic Workflows

زیرعامل‌ها از قبل به شما اجازه می‌دهند «یک کلون بفرستید» تا یک موضوع را به‌صورت موازی بررسی کند. اما وقتی کاری آن‌قدر بزرگ است که به «یک تیم کامل» نیاز دارد — مثلاً جاروب کل یک مخزن و نوشتن بازبینی برای هر ماژول — یک زیرعامل کافی نیست. اینجاست که **Dynamic Workflows** وارد می‌شود.

Dynamic Workflows به Claude Code اجازه می‌دهد **ده‌ها تا صدها زیرعامل پس‌زمینه** را در یک اجرا هماهنگ کند، به‌طوری که هر کدام بخشی از کار را برمی‌دارند و به‌صورت موازی اجرا می‌شوند، در حالی که شما به کار خودتان ادامه می‌دهید. این قابلیت روی هر مدلی اجرا می‌شود که Claude Code در حال حاضر با آن پیکربندی شده است — بنابراین تا زمانی که Claude Code را به QCode متصل کنید، گردش‌کارها بدون تنظیم اضافی کار می‌کنند.

## چه مشکلی را حل می‌کند

زیرعامل‌های معمولی برای کارهای موازی «چندتایی و کنترل‌شده» عالی‌اند: 2–3 کلون بفرستید تا به‌ترتیب API، اسکیما و پوشش تست را بررسی کنند. اما برخی کارها ذاتاً به‌شدت موازی‌پذیرند:

- انجام **بازبینی امنیتی/کیفی برای هر فایل** در مخزنی با 200 فایل
- **مهاجرت دسته‌ای** یک فراخوانی API قدیمی به سبکی جدید در کل پایگاه کد
- پیرامون یک موضوع، **پژوهش جداگانه روی ده‌ها پوشه** و سپس خلاصه‌سازی

اگر این کارها را سریالی انجام دهید، باید منتظر بمانید تا Claude یکی‌یکی آن‌ها را انجام دهد؛ و راه‌اندازی دستی ده‌ها زیرعامل یعنی خودتان کارها را تقسیم می‌کنید و پیشرفت را دائم زیر نظر می‌گیرید. Dynamic Workflows کل چرخه «تقسیم → توزیع → اجرا در پس‌زمینه → خلاصه‌سازی» را به Claude Code می‌سپارد تا خودش آن را هماهنگ کند.

## نحوه فعال‌سازی

Dynamic Workflows به نصب اضافی نیاز ندارد و فعال‌سازی آن سبک است:

- کلیدواژه **`ultracode`** را در prompt خود قرار دهید؛ یا
- کافی است از آن بخواهید **«یک گردش‌کار اجرا کن»**.

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

```
> ultracode review every submodule under src/, focusing on error handling
> and input validation. Have each module output a short report, then roll
> everything up into one overview.
```

یا با زبان طبیعی ساده:

```
> Run a workflow for me: scan the whole repo for every call to the old
> httpClient, estimate the effort to migrate to the new fetch wrapper, and
> summarize grouped by directory.
```
## مشاهده اجراها با /workflows

زیرعامل‌هایی که یک گردش‌کار ارسال می‌کند **در پس‌زمینه به اجرا ادامه می‌دهند** — نشست اصلی شما را مسدود نمی‌کنند، بنابراین می‌توانید به پرسیدن پرسش‌های دیگر و نوشتن کد ادامه دهید. برای دیدن اینکه کدام گردش‌کارها در حال اجرا هستند و تا چه حد پیش رفته‌اند، از این فرمان استفاده کنید:

```
/workflows
```

این فرمان اجراهای در حال انجام و تکمیل‌شده گردش‌کار را فهرست می‌کند و پیگیری پیشرفت کلی و بررسی خروجی هر زیرعامل را آسان می‌سازد.

> اجرای پس‌زمینه یعنی کارهای بزرگ دیگر تعامل شما را مسدود نمی‌کنند. دستور را ارسال کنید، به کار دیگری بروید و بعداً برای جمع‌آوری نتایج با `/workflows` بازگردید.

## زمان استفاده از گردش‌کار در برابر یک زیرعامل

این دو، همان ایده «واگذاری موازی» در مقیاس‌های متفاوت‌اند و انتخاب ساده است: **همه‌چیز به مقیاس موازی و اینکه آیا نیاز دارید آن را در پس‌زمینه اجرا کنید بستگی دارد.**

| معیار | یک زیرعامل | Dynamic Workflow |
|-----------|-----------------|------------------|
| مقیاس موازی | چند زیرکار مستقل | از ده‌ها تا صدها زیرکار |
| محرک | از Claude بخواهید «یک زیرعامل برای بررسی X بفرستد» | کلیدواژه `ultracode` یا «یک گردش‌کار اجرا کن» |
| محل اجرا | پس از پایان، خلاصه‌ای به نشست اصلی برمی‌گرداند | در پس‌زمینه به اجرا ادامه می‌دهد و نشست اصلی را مسدود نمی‌کند |
| روش مشاهده | نتیجه به‌صورت درون‌خطی در گفتگو برمی‌گردد | از `/workflows` برای دیدن فهرست اجراها استفاده کنید |
| کاربرد معمول | بررسی‌های موازی API / اسکیما / تست‌ها | بازبینی کل مخزن / مهاجرت دسته‌ای / تحقیق در مقیاس بزرگ |

قاعده سرانگشتی:

- **فقط چند** زیرکار دارید و می‌خواهید نتیجه را فوراً بگیرید → از [زیرعامل‌ها](/docs/advanced/subagents) استفاده کنید.
- **ده‌ها یا صدها** زیرکار که می‌توانند در پس‌زمینه اجرا شوند → از Dynamic Workflows استفاده کنید.

> Dynamic Workflows در اصل نسخه «بزرگ‌شده» زیرعامل‌هاست. ابتدا با مفهوم [زیرعامل‌ها](/docs/advanced/subagents) راحت شوید؛ آن‌گاه گردش‌کارها طبیعی به نظر می‌رسند.

## استفاده از آن از طریق QCode

Dynamic Workflows روی **هر مدلی که Claude Code به آن متصل است** اجرا می‌شود و به هیچ ارائه‌دهنده خاصی وابسته نیست. یعنی وقتی Claude Code را به QCode متصل می‌کنید، هر زیرعامل پس‌زمینه‌ای که یک گردش‌کار ارسال می‌کند از نقاط پایانی QCode عبور می‌کند — همان کلید API که با `cr_` شروع می‌شود در همه‌جا کار می‌کند.

راه‌اندازی حداقلی (پروتکل Anthropic):

```bash
export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_key"

# Users in China should prefer the asia endpoint
# export ANTHROPIC_BASE_URL="https://asia.qcode.cc/api"
```

> `BASE_URL` **نباید** اسلش انتهایی داشته باشد. دسترسی مستقیم به آن آدرس `401` برمی‌گرداند که طبیعی است — یعنی مسیر درست است و فقط احراز هویت وجود ندارد.

پس از پیکربندی، Claude Code را طبق معمول اجرا کنید و با `ultracode` یک گردش‌کار را راه‌اندازی کنید. برای مرجع کامل نقاط پایانی، سه دامنه (api / asia / us) و مسیرهای هر پروتکل، [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths) را ببینید.

هزینه هر زیرعامل پس‌زمینه در یک گردش‌کار بر اساس مدلی که در QCode انتخاب کرده‌اید محاسبه می‌شود. یک گردش‌کار بزرگ بسیاری از زیرعامل‌ها را هم‌زمان اجرا می‌کند، بنابراین مصرف توکن به‌تناسب افزایش می‌یابد — پیش از یک اجرای بزرگ، بهتر است با یک مدل پرچم‌دار (مثلاً `claude-opus-5`، $5/$25 به‌ازای هر میلیون توکن، پنجره زمینه 1M) یک آزمایش محدود انجام دهید، کیفیت خروجی را تأیید کنید و تنها پس از آن آن را به‌طور کامل اجرا کنید.
## نمونه‌های کاربردی

### نمونه 1: بازبینی کد در کل مخزن

از workflow بخواهید برای هر ماژول اصلی در سراسر مخزن یک بازبینی تولید کند، با تمرکز و خروجی یکسان، و سپس همه را تجمیع کنید:

```
> ultracode do an independent code review of every sub-package under packages/.
> Each review should cover: error handling, edge cases, any unhandled Promises,
> naming consistency. Each sub-package outputs a bullet list of no more than 20
> lines, then roll everything up into one master table sorted by severity.
```

پس از ارسال، می‌توانید به کارهای دیگر خود ادامه دهید، بعداً پیشرفت را با `/workflows` بررسی کنید و پس از پایان همه عامل‌های فرعی، جدول تجمیع‌شده را مرور کنید.

### نمونه 2: پژوهش مهاجرت API در مقیاس بزرگ

پیش از هر تغییری، با یک workflow دامنه تأثیر را مشخص کنید:

```
> Run a workflow for me: find everywhere in the codebase that uses axios
> directly, group by directory, estimate the effort and risk of switching to
> the in-project httpClient wrapper, and output a table of
> "directory / occurrences / migration difficulty / caveats".
```

با تصویر کامل، می‌توانید ترتیب مهاجرت را بر پایه داده‌های واقعی و نه حس شهودی تعیین کنید.

## نکته‌ها و ملاحظات

- **کوچک شروع کنید، سپس گسترش دهید**: در نخستین اجرا، workflow را به یک پوشه یا بسته محدود کنید، بررسی کنید که قالب و کیفیت خروجی با انتظار شما مطابقت دارد و سپس آن را به کل مخزن گسترش دهید.
- **قالب خروجی را یکسان کنید**: در prompt صریح بنویسید که هر عامل فرعی «چه چیزی، با چه طولی و با چه ترتیبی» خروجی بدهد — این کار در زمان تجمیع تلاش زیادی را ذخیره می‌کند.
- **اجرا در پس‌زمینه به معنای بی‌نظارت بودن نیست**: در حین اجرای workflow می‌توانید کارهای دیگر انجام دهید، اما یادتان باشد برگردید و کار را با `/workflows` جمع‌بندی کنید.
- **درباره تصاویر**: Dynamic Workflows وظایف متنی/کدی را انجام می‌دهد. اگر می‌خواهید Claude Code **تصاویر را بخواند** (اسکرین‌شات‌ها، نمودارهای معماری، اسکرین‌شات خطاها)، آن قابلیت ورودی تصویری است و ارتباطی با workflow ندارد؛ اگر می‌خواهید **تصویر تولید کنید**، از [تولید تصویر با gpt-image-2](/docs/usage/image-2) استفاده کنید.
- برای اتصال workflowها به CI/اسکریپت‌ها، حالت headless را با خروجی ساختاریافته ترکیب کنید — به [خودکارسازی و CI/CD](/docs/advanced/headless) مراجعه کنید.

## محرک‌ها و تنظیمات کلیدی

بر اساس مستندات رسمی Dynamic Workflows در Claude Code، تا تاریخ 2026-10-15:

| تنظیم / اقدام | اثر | توضیحات |
|---|---|---|
| `ultracode` در یک prompt، یا «run a workflow» | فقط همین یک وظیفه را به‌صورت workflow اجرا می‌کند | این کلیدواژه فقط زمانی کار می‌کند که خودتان در یک نشست تعاملی prompt را تایپ کنید؛ محتوایی که از طریق `-p`، وظایف زمان‌بندی‌شده یا webhookها می‌رسد آن را فعال نمی‌کند |
| `/effort ultracode` | Claude برای هر وظیفه اساسی در نشست یک workflow برنامه‌ریزی می‌کند | `claude --effort ultracode` آن را هنگام اجرا روشن می‌کند (و effort را روی `xhigh` تنظیم می‌کند)؛ `/effort ultracode off` آن را خاموش می‌کند. تا زمانی که روشن است، هر درخواست توکن بیشتری مصرف می‌کند و زمان بیشتری می‌برد |
| اندازه workflow پویا در `/config` (`workflowSizeGuideline`) | به Claude می‌گوید تقریباً چند عامل را هدف بگیرد | `small` کمتر از 5، `medium` کمتر از 10 (پیش‌فرض)، `large` کمتر از 50، `unrestricted` بدون راهنما؛ این فقط یک توصیه است، نه سقف |
| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | تعداد عامل‌های در حال اجرا به‌طور هم‌زمان | به‌طور پیش‌فرض تا 16 اجرای هم‌زمان؛ می‌توان آن را از 1 تا 256 تنظیم کرد (نیازمند Claude Code v2.1.269 یا جدیدتر) |
| محدودیت‌های اندازه اجرا | جلوگیری از اجراهای بی‌کنترل | در مجموع 1,000 عامل در هر اجرا؛ حداکثر 4,096 آیتم در یک فراخوانی `parallel()` / `pipeline()` |

در `/workflows`، یک اجرا را انتخاب کنید و `s` را بزنید تا اسکریپت آن به‌عنوان دستور اختصاصی خودتان ذخیره شود: ذخیره در `.claude/workflows/` پروژه آن را با مخزن به اشتراک می‌گذارد، و ذخیره در `~/.claude/workflows/` آن را فقط برای خودتان نگه می‌دارد.
## اجرای گردش‌کارها از طریق QCode: نکاتی که باید بدانید

- **هم‌زمانی و محدودیت نرخ درخواست**: یک گردش‌کار به‌طور پیش‌فرض می‌تواند 16 عامل را هم‌زمان اجرا کند، در حالی که پلن شخصی QCode یا بسته پرداخت به‌ازای مصرف، 5 درخواست هم‌زمان به‌ازای هر کلید API را مجاز می‌داند (10 در Ultimate؛ [پرسش‌های متداول](/docs/reference/faq) را ببینید). اگر یک اجرای بزرگ به محدودیت نرخ درخواست بربخورد (معمولاً 429) یا عامل‌های جداگانه شکست بخورند، ابتدا `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` را تا مقداری هم‌راستا با هم‌زمانی پلن خود کاهش دهید و دوباره تلاش کنید.
- **هزینه**: توکن‌های هر عامل بر اساس مدلی که انتخاب کرده‌اید صورت‌حساب می‌شود؛ QCode به‌ازای هر توکن صورت‌حساب می‌کند و نرخ هر مدل در [qcode.cc/models](https://qcode.cc/models) آمده است. مستندات می‌گوید وقتی یک اجرا بیش از 25 عامل را زمان‌بندی کند یا مجموع برآوردی آن از 1.5 میلیون توکن فراتر رود، پنل وظیفه هشدار «Large workflow» را نشان می‌دهد؛ این هشدار فقط جنبه اطلاع‌رسانی دارد و اجرا را متوقف نمی‌کند. امن‌ترین شروع، آزمایش روی یک دایرکتوری یا یک پرسش محدود است.
- **مدل**: مگر اینکه خلاف آن را مشخص کنید، عامل‌ها از مدل جاری نشست استفاده می‌کنند. برای مراحل سبک می‌توانید هنگام توصیف وظیفه، مدل سبک‌تری مانند `claude-haiku-5-5` درخواست کنید.

## خطاهای رایج و روش عیب‌یابی

| نشانه | علت | راه‌حل |
|---|---|---|
| `ultracode` را نوشتید اما هیچ گردش‌کاری شروع نشد | prompt را خودتان به‌صورت تعاملی تایپ نکردید (مثلاً `-p`، یک وظیفه زمان‌بندی‌شده)، یا محرک کلیدواژه در `/config` خاموش شده است | از یک prompt تعاملی استفاده کنید، یا مستقیماً بگویید «run a workflow» |
| گردش‌کار در حالت `-p` شروع نمی‌شود | آن حالت هیچ prompt تأییدی نشان نمی‌دهد و بر اساس قواعد مجوز تصمیم می‌گیرد | `Workflow` را به قواعد مجاز خود اضافه کنید، یا از حالت مجوز خودکار / bypass استفاده کنید |
| برخی عامل‌ها چیزی برنمی‌گردانند، یا به نظر می‌رسد محدودیت نرخ درخواست اعمال شده است (معمولاً 429) | هم‌زمانی ممکن است از حد هم‌زمانی کلید شما فراتر رفته باشد | `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` را کاهش دهید، سپس از Claude بخواهید همان گردش‌کار را دوباره اجرا کند |
| `agent stalled on all 6 attempts` | یک عامل مدت‌ها هیچ خروجی‌ای تولید نکرد | راه‌حل رسمی: پنجره توقف (`CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`) را طولانی‌تر کنید، یا در اسکریپت برای آن عامل `stallMs` را تنظیم کنید |
| `agent lost its reply on all 6 attempts` | جریان پاسخ بی‌صدا شد و نگهبان بی‌کاری آن را قطع کرد | تنظیمی که باید افزایش دهید `CLAUDE_STREAM_IDLE_TIMEOUT_MS` است، نه پنجره توقف |
| `nothing to resume` | نتایج ذخیره‌شده اجرای قبلی پیدا نمی‌شود | از Claude بخواهید گردش‌کار را به‌عنوان یک اجرای جدید از نو شروع کند |
| 401 / 404 | ارتباطی به گردش‌کارها ندارد؛ مشکلی در تنظیمات اتصال است | خودآزمایی را در [نقاط پایانی و قالب‌های API](/docs/getting-started/endpoints-and-api-paths) اجرا کنید |

## پرسش‌های متداول

### آیا می‌توانم پس از ترک نشست ادامه دهم؟

در همان نشست، بله: از Claude بخواهید همان گردش‌کار را دوباره اجرا کند؛ عامل‌های تکمیل‌شده نتایج ذخیره‌شده خود را برمی‌گردانند، در حالی که عامل‌های ناموفق و آن‌هایی که پس از آن‌ها شروع شده‌اند دوباره اجرا می‌شوند. پس از خروج، `claude --resume` نشست را بازمی‌گرداند و اجرا را می‌توان بازپخش کرد؛ نشستی که تازه شروع شده هیچ سابقه‌ای از اجرای قبلی ندارد.

### یک اجرا چند عامل می‌تواند ایجاد کند؟

حد رسمی 1,000 عامل در هر اجرا است و به‌طور پیش‌فرض 16 عامل هم‌زمان اجرا می‌شوند. این‌ها محدودیت‌های خود Claude Code هستند؛ محدودیت هم‌زمانی QCode جداگانه است، همان‌طور که در بالا توضیح داده شد.

### آیا یک گردش‌کار گران تمام می‌شود؟

این روش نسبت به انجام همان کار به‌صورت گام‌به‌گام در گفتگو، توکن بیشتری مصرف می‌کند. ابتدا یک برش کوچک را امتحان کنید، مصرف توکن هر عامل را در `/workflows` بررسی کنید و در صورت نیاز اجرا را هر زمان که خواستید متوقف کنید.

### آیا عامل‌های یک گردش‌کار از تنظیمات مجوز من پیروی می‌کنند؟

بله. مستندات بیان می‌کند که فراخوانی ابزارهای عامل‌ها از همان بررسی‌های مجوز و سندباکسی عبور می‌کند که هر فراخوانی ابزار در نشست شما از آن‌ها می‌گذرد؛ کلیدواژه `ultracode` تنها مشخص می‌کند کار چگونه سازمان‌دهی شود.

### چگونه به تیم خود اجازه دهم یک گردش‌کار را دوباره استفاده کند؟

در `/workflows`، اجرا را انتخاب کنید و `s` را بزنید، سپس آن را در `.claude/workflows/` پروژه ذخیره کنید تا از طریق مخزن برای همه به اشتراک گذاشته شود.

> می‌خواهید گردش‌کارهای بزرگ‌مقیاس را با یک مدل پرچمدار اجرا کنید و در همان حال هزینه را زیر نظر داشته باشید؟ [قیمت‌گذاری QCode](https://qcode.cc/pricing) را ببینید — یک کلید API در تمام نقاط پایانی کار می‌کند.