ساختِ ساب‌ایجنت‌های سفارشی

این یک ترجمهٔ غیررسمی از مستندات Claude Code است که توسط مسیر تهیه شده. نسخهٔ مرجع و معتبر، مستندات رسمی انگلیسی است.

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

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

یادداشت

ساب‌ایجنت‌ها درونِ یک نشستِ واحد کار می‌کنند. برای اجرای چند نشستِ مستقل به‌صورت موازی و پایشِ آن‌ها از یک‌جا، background agents را ببین. برای نشست‌هایی که با هم ارتباط برقرار می‌کنند، agent teams را ببین.

ساب‌ایجنت‌ها به تو کمک می‌کنند:

• کانتکست را حفظ کنی با نگه‌داشتنِ اکتشاف و پیاده‌سازی بیرون از گفت‌وگوی اصلی‌ات
• محدودیت اعمال کنی با مقیدکردنِ ابزارهایی که یک ساب‌ایجنت می‌تواند استفاده کند
• پیکربندی‌ها را بازاستفاده کنی در پروژه‌های مختلف با ساب‌ایجنت‌های سطحِ کاربر
• رفتار را تخصصی کنی با پرامپت‌های سیستمیِ متمرکز برای حوزه‌های خاص
• هزینه را کنترل کنی با مسیریابیِ کارها به مدل‌های سریع‌تر و ارزان‌تر مثل Haiku

Claude از توصیفِ هر ساب‌ایجنت استفاده می‌کند تا تصمیم بگیرد کِی کار را به آن بسپارد. وقتی یک ساب‌ایجنت می‌سازی، یک توصیفِ روشن بنویس تا Claude بداند کِی باید از آن استفاده کند.

Claude Code چند ساب‌ایجنتِ توکار دارد مثل Explore، Plan و general-purpose. می‌توانی ساب‌ایجنت‌های سفارشی هم بسازی تا کارهای خاص را انجام دهند. این صفحه این موارد را پوشش می‌دهد:

• ساب‌ایجنت‌های توکار
• چطور خودت بسازی
• همه‌ی گزینه‌های پیکربندی
• الگوهای کار با ساب‌ایجنت‌ها
• ساب‌ایجنت‌های Fork‌شده
• نمونه ساب‌ایجنت‌ها

ساب‌ایجنت‌های توکار

Claude Code ساب‌ایجنت‌های توکاری دارد که Claude در مواقعِ مناسب خودکار از آن‌ها استفاده می‌کند. هرکدام مجوزهای گفت‌وگوی والد را با محدودیت‌های اضافیِ ابزار به ارث می‌برند.

Explore و Plan فایل‌های CLAUDE.md تو و وضعیتِ git نشستِ والد را نادیده می‌گیرند تا تحقیق سریع و کم‌هزینه بماند. هر ساب‌ایجنتِ توکار و سفارشیِ دیگری هر دو را بارگذاری می‌کند. برای تفکیکِ کاملِ آنچه به یک ساب‌ایجنت می‌رسد، چه چیزهایی در شروع بارگذاری می‌شوند را ببین.

Explore

یک ایجنتِ سریع و فقط‌خواندنی که برای جست‌وجو و تحلیلِ کدبیس‌ها بهینه شده.

• مدل: Haiku (سریع، با تأخیرِ کم)
• ابزارها: ابزارهای فقط‌خواندنی (دسترسی به ابزارهای Write و Edit رد شده)
• هدف: کشفِ فایل، جست‌وجوی کد، اکتشافِ کدبیس

Claude وقتی نیاز دارد بدونِ ایجادِ تغییر، کدبیسی را جست‌وجو یا درک کند، کار را به Explore می‌سپارد. این کار نتایجِ اکتشاف را بیرونِ کانتکستِ گفت‌وگوی اصلی‌ات نگه می‌دارد.

هنگامِ فراخوانیِ Explore، Claude یک سطحِ دقت مشخص می‌کند: quick برای جست‌وجوهای هدفمند، medium برای اکتشافِ متعادل، یا very thorough برای تحلیلِ جامع.

Plan

یک ایجنتِ تحقیقاتی که در حالتِ planning برای جمع‌آوریِ کانتکست پیش از ارائه‌ی یک طرح استفاده می‌شود.

• مدل: از گفت‌وگوی اصلی به ارث می‌برد
• ابزارها: ابزارهای فقط‌خواندنی (دسترسی به ابزارهای Write و Edit رد شده)
• هدف: تحقیقِ کدبیس برای برنامه‌ریزی

وقتی در حالتِ planning هستی و Claude نیاز دارد کدبیست را درک کند، تحقیق را به ساب‌ایجنتِ Plan می‌سپارد تا خروجیِ اکتشاف در یک پنجره‌ی کانتکستِ جداگانه بماند و گفت‌وگوی اصلی فقط‌خواندنی باقی بماند.

General-purpose

یک ایجنتِ توانمند برای کارهای پیچیده و چندمرحله‌ای که هم به اکتشاف و هم به کنش نیاز دارند.

• مدل: از گفت‌وگوی اصلی به ارث می‌برد
• ابزارها: همه‌ی ابزارها
• هدف: تحقیقِ پیچیده، عملیاتِ چندمرحله‌ای، تغییرِ کد

Claude وقتی کار هم به اکتشاف و هم به تغییر نیاز دارد، یا برای تفسیرِ نتایج به استدلالِ پیچیده، یا به چند مرحله‌ی وابسته به هم نیاز است، کار را به general-purpose می‌سپارد.

Other

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

ایجنت	مدل	کِی Claude از آن استفاده می‌کند
statusline-setup	Sonnet	وقتی /statusline را اجرا می‌کنی تا نوارِ وضعیتت را پیکربندی کنی
claude-code-guide	Haiku	وقتی درباره‌ی قابلیت‌های Claude Code سؤال می‌پرسی

ساب‌ایجنت‌های توکار همیشه در نشست‌های تعاملی ثبت‌شده‌اند. برای مسدودکردنِ یک نوعِ توکارِ مشخص، آن را به permissions.deny اضافه کن، همان‌طور که در غیرفعال‌کردنِ ساب‌ایجنت‌های مشخص نشان داده شده. برای جلوگیری از سپردنِ کار توسط Claude به هر ساب‌ایجنتی، خودِ ابزارِ Agent را با permissions.deny رد کن. در حالتِ غیرتعاملی و Agent SDK، متغیرِ CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 را تنظیم کن تا همه‌ی انواعِ توکار حذف شوند و فقط ساب‌ایجنت‌های خودت بمانند.

فراتر از این ساب‌ایجنت‌های توکار، می‌توانی ساب‌ایجنت‌های خودت را با پرامپت‌های سفارشی، محدودیتِ ابزار، حالتِ مجوز، hooks و skills بسازی. بخش‌های بعدی نشان می‌دهند چطور شروع کنی و ساب‌ایجنت‌ها را سفارشی کنی.

شروعِ سریع: اولین ساب‌ایجنتت را بساز

ساب‌ایجنت‌ها در فایل‌های Markdown با frontmatterِ YAML تعریف می‌شوند. می‌توانی دستی بسازی‌شان یا از دستورِ /agents استفاده کنی.

این راهنما تو را در ساختِ یک ساب‌ایجنتِ سطحِ کاربر با دستورِ /agents همراهی می‌کند. این ساب‌ایجنت کد را بازبینی می‌کند و برای کدبیس بهبود پیشنهاد می‌دهد.

رابطِ ساب‌ایجنت‌ها را باز کن

در Claude Code، اجرا کن:

/agents

یک محل انتخاب کن

به تبِ Library برو، Create new agent را انتخاب کن، بعد Personal را بزن. این کار ساب‌ایجنت را در ~/.claude/agents/ ذخیره می‌کند تا در همه‌ی پروژه‌هایت در دسترس باشد.

با Claude بساز

Generate with Claude را انتخاب کن. وقتی پرسیده شد، ساب‌ایجنت را توصیف کن:

A code improvement agent that scans files and suggests improvements
for readability, performance, and best practices. It should explain
each issue, show the current code, and provide an improved version.

Claude شناسه، توصیف و پرامپتِ سیستمی را برایت می‌سازد.

ابزارها را انتخاب کن

برای یک بازبینِ فقط‌خواندنی، همه‌چیز جز Read-only tools را از انتخاب خارج کن. اگر همه‌ی ابزارها را انتخاب‌شده نگه داری، ساب‌ایجنت همه‌ی ابزارهای در دسترسِ گفت‌وگوی اصلی را به ارث می‌برد.

مدل را انتخاب کن

انتخاب کن ساب‌ایجنت از کدام مدل استفاده کند. برای این ایجنتِ نمونه، Sonnet را انتخاب کن، که برای تحلیلِ الگوهای کد بینِ توانایی و سرعت تعادل برقرار می‌کند.

یک رنگ انتخاب کن

یک رنگِ پس‌زمینه برای ساب‌ایجنت بردار. این کمکت می‌کند تشخیص دهی کدام ساب‌ایجنت در UI در حالِ اجراست.

حافظه را پیکربندی کن

User scope را انتخاب کن تا به ساب‌ایجنت یک دایرکتوریِ حافظه‌ی ماندگار در ~/.claude/agent-memory/ بدهی. ساب‌ایجنت از این برای انباشتِ بینش‌ها در طولِ گفت‌وگوها استفاده می‌کند، مثلِ الگوهای کدبیس و مسائلِ تکرارشونده. اگر نمی‌خواهی ساب‌ایجنت آموخته‌هایش را ماندگار کند، None را انتخاب کن.

ذخیره کن و امتحانش کن

خلاصه‌ی پیکربندی را مرور کن. s یا Enter را بزن تا ذخیره شود، یا e را بزن تا ذخیره شود و فایل را در ویرایشگرت ویرایش کنی. ساب‌ایجنت بلافاصله در دسترس است. امتحانش کن:

Use the code-improver agent to suggest improvements in this project

Claude کار را به ساب‌ایجنتِ تازه‌ات می‌سپارد، که کدبیس را اسکن می‌کند و پیشنهادهای بهبود برمی‌گرداند.

حالا یک ساب‌ایجنت داری که می‌توانی در هر پروژه‌ای روی دستگاهت برای تحلیلِ کدبیس‌ها و پیشنهادِ بهبود استفاده کنی.

می‌توانی ساب‌ایجنت‌ها را دستی هم به‌صورت فایل‌های Markdown بسازی، با پرچم‌های CLI تعریف کنی، یا از طریقِ پلاگین‌ها توزیع کنی. بخش‌های بعدی همه‌ی گزینه‌های پیکربندی را پوشش می‌دهند.

پیکربندیِ ساب‌ایجنت‌ها

استفاده از دستورِ /agents

دستورِ /agents یک رابطِ تب‌دار برای مدیریتِ ساب‌ایجنت‌ها باز می‌کند. تبِ Running ساب‌ایجنت‌های زنده و تازه‌تمام‌شده را فهرست می‌کند و می‌گذارد بازشان کنی یا متوقفشان کنی. تبِ Library می‌گذارد:

• همه‌ی ساب‌ایجنت‌های در دسترس (توکار، کاربر، پروژه و پلاگین) را ببینی
• ساب‌ایجنت‌های جدید را با راه‌اندازیِ راهنمابه‌دست یا ساختِ Claude بسازی
• پیکربندی و دسترسیِ ابزارِ ساب‌ایجنت‌های موجود را ویرایش کنی
• ساب‌ایجنت‌های سفارشی را حذف کنی
• ببینی وقتی نسخه‌های تکراری وجود دارند کدام ساب‌ایجنت‌ها فعال‌اند

این روشِ توصیه‌شده برای ساختن و مدیریتِ ساب‌ایجنت‌هاست. برای ساختِ دستی یا اتوماسیون، می‌توانی فایل‌های ساب‌ایجنت را مستقیم هم اضافه کنی.

دامنه‌ی ساب‌ایجنت را انتخاب کن

ساب‌ایجنت‌ها فایل‌های Markdown با frontmatterِ YAML هستند. بسته به دامنه آن‌ها را در محل‌های مختلف ذخیره کن. وقتی چند ساب‌ایجنت نامِ یکسانی دارند، محلِ با اولویتِ بالاتر برنده می‌شود.

محل	دامنه	اولویت	چطور ساخته می‌شود
تنظیماتِ مدیریت‌شده	سراسرِ سازمان	۱ (بالاترین)	از طریقِ تنظیماتِ مدیریت‌شده مستقر می‌شود
پرچمِ CLI با --agents	نشستِ جاری	۲	هنگامِ راه‌اندازیِ Claude Code، JSON پاس بده
.claude/agents/	پروژه‌ی جاری	۳	تعاملی یا دستی
~/.claude/agents/	همه‌ی پروژه‌هایت	۴	تعاملی یا دستی
دایرکتوریِ agents/ پلاگین	جایی که پلاگین فعال است	۵ (پایین‌ترین)	همراهِ پلاگین‌ها نصب می‌شود

ساب‌ایجنت‌های پروژه (.claude/agents/) برای ساب‌ایجنت‌های مختصِ یک کدبیس ایده‌آل‌اند. آن‌ها را به کنترلِ نسخه بسپار تا تیمت بتواند به‌صورت مشترک از آن‌ها استفاده و بهبودشان دهد.

ساب‌ایجنت‌های پروژه با بالارفتن از دایرکتوریِ کاریِ جاری کشف می‌شوند. دایرکتوری‌هایی که با --add-dir اضافه شده‌اند فقط دسترسیِ فایل می‌دهند و برای ساب‌ایجنت‌ها اسکن نمی‌شوند. برای به‌اشتراک‌گذاریِ ساب‌ایجنت‌ها بینِ پروژه‌ها، از ~/.claude/agents/ یا یک پلاگین استفاده کن.

ساب‌ایجنت‌های کاربر (~/.claude/agents/) ساب‌ایجنت‌های شخصی‌اند که در همه‌ی پروژه‌هایت در دسترس‌اند.

Claude Code دایرکتوری‌های .claude/agents/ و ~/.claude/agents/ را به‌صورت بازگشتی اسکن می‌کند، پس می‌توانی تعریف‌ها را در زیرپوشه‌هایی مثلِ agents/review/ یا agents/research/ سامان دهی. مسیرِ زیردایرکتوری روی نحوه‌ی شناسایی یا فراخوانیِ یک ساب‌ایجنت اثر ندارد، چون هویت فقط از فیلدِ name در frontmatter می‌آید. مقدارهای name را در کلِ درخت یکتا نگه دار: اگر دو فایل در یک دامنه نامِ یکسان اعلام کنند، Claude Code یکی را نگه می‌دارد و دیگری را بدونِ هشدار دور می‌اندازد.

دایرکتوری‌های agents/ پلاگین هم به‌صورت بازگشتی اسکن می‌شوند. برخلافِ دامنه‌های پروژه و کاربر، یک زیرپوشه درونِ دایرکتوریِ agents/ یک پلاگین به بخشی از شناسه‌ی دامنه‌دار تبدیل می‌شود: فایلی در agents/review/security.md در پلاگینِ my-plugin به‌صورتِ my-plugin:review:security ثبت می‌شود.

ساب‌ایجنت‌های تعریف‌شده با CLI هنگامِ راه‌اندازیِ Claude Code به‌صورتِ JSON پاس داده می‌شوند. آن‌ها فقط برای همان نشست وجود دارند و روی دیسک ذخیره نمی‌شوند، که برای آزمایشِ سریع یا اسکریپت‌های اتوماسیون مفیدشان می‌کند. می‌توانی چند ساب‌ایجنت را در یک فراخوانیِ --agents تعریف کنی:

macOS، Linux، WSL

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

Windows PowerShell

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

پرچمِ --agents همان فیلدهای frontmatterِ ساب‌ایجنت‌های فایل‌محور را به‌صورتِ JSON می‌پذیرد: description، prompt، tools، disallowedTools، model، permissionMode، mcpServers، hooks، maxTurns، skills، initialPrompt، memory، effort، background، isolation و color. از prompt برای پرامپتِ سیستمی استفاده کن، که معادلِ بدنه‌ی markdown در ساب‌ایجنت‌های فایل‌محور است.

ساب‌ایجنت‌های مدیریت‌شده را مدیرانِ سازمان مستقر می‌کنند. فایل‌های markdown را در .claude/agents/ درونِ دایرکتوریِ تنظیماتِ مدیریت‌شده قرار بده، با همان قالبِ frontmatterِ ساب‌ایجنت‌های پروژه و کاربر. تعریف‌های مدیریت‌شده بر ساب‌ایجنت‌های پروژه و کاربر با نامِ یکسان اولویت دارند.

ساب‌ایجنت‌های پلاگین از پلاگین‌هایی می‌آیند که نصب کرده‌ای. آن‌ها در /agents کنارِ ساب‌ایجنت‌های سفارشی‌ات ظاهر می‌شوند. برای جزئیاتِ ساختِ ساب‌ایجنت‌های پلاگین، مرجعِ اجزای پلاگین را ببین.

یادداشت

به دلایلِ امنیتی، ساب‌ایجنت‌های پلاگین از فیلدهای hooks، mcpServers یا permissionMode در frontmatter پشتیبانی نمی‌کنند. این فیلدها هنگامِ بارگذاریِ ایجنت‌ها از یک پلاگین نادیده گرفته می‌شوند. اگر به آن‌ها نیاز داری، فایلِ ایجنت را در .claude/agents/ یا ~/.claude/agents/ کپی کن. می‌توانی قواعدی را هم به permissions.allow در settings.json یا settings.local.json اضافه کنی، اما این قواعد بر کلِ نشست اعمال می‌شوند، نه فقط ساب‌ایجنتِ پلاگین.

تعریف‌های ساب‌ایجنت از هرکدام از این دامنه‌ها برای agent teams هم در دسترس‌اند: هنگامِ ایجادِ یک هم‌تیمی، می‌توانی به یک نوعِ ساب‌ایجنت ارجاع دهی و هم‌تیمی از tools و model آن استفاده می‌کند، و بدنه‌ی تعریف به‌عنوانِ دستورهای اضافی به پرامپتِ سیستمیِ هم‌تیمی الحاق می‌شود. برای اینکه ببینی در آن مسیر کدام فیلدهای frontmatter اعمال می‌شوند، agent teams را ببین.

نوشتنِ فایل‌های ساب‌ایجنت

فایل‌های ساب‌ایجنت برای پیکربندی از frontmatterِ YAML استفاده می‌کنند و پس از آن پرامپتِ سیستمی به‌صورتِ Markdown می‌آید:

یادداشت

ساب‌ایجنت‌ها در شروعِ نشست بارگذاری می‌شوند. اگر فایلِ یک ساب‌ایجنت را مستقیم روی دیسک اضافه یا ویرایش کنی، نشستت را ری‌استارت کن تا بارگذاری شود. ساب‌ایجنت‌هایی که از طریقِ رابطِ /agents ساخته می‌شوند بدونِ ری‌استارت بلافاصله اعمال می‌شوند.

---
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.

frontmatter متادیتا و پیکربندیِ ساب‌ایجنت را تعریف می‌کند. بدنه به پرامپتِ سیستمی‌ای تبدیل می‌شود که رفتارِ ساب‌ایجنت را هدایت می‌کند. ساب‌ایجنت‌ها فقط همین پرامپتِ سیستمی را دریافت می‌کنند (به‌علاوه‌ی جزئیاتِ پایه‌ای محیط مثلِ دایرکتوریِ کاری)، نه کلِ پرامپتِ سیستمیِ Claude Code.

یک ساب‌ایجنت در دایرکتوریِ کاریِ جاریِ گفت‌وگوی اصلی شروع می‌شود. درونِ یک ساب‌ایجنت، دستورهای cd بینِ فراخوانی‌های ابزارِ Bash یا PowerShell پایدار نمی‌مانند و روی دایرکتوریِ کاریِ گفت‌وگوی اصلی اثر نمی‌گذارند. برای اینکه به‌جای آن یک کپیِ ایزوله از مخزن به ساب‌ایجنت بدهی، isolation: worktree را تنظیم کن.

فیلدهای frontmatterِ پشتیبانی‌شده

فیلدهای زیر را می‌توان در frontmatterِ YAML استفاده کرد. فقط name و description الزامی‌اند.

فیلد	الزامی	توضیح
name	بله	شناسه‌ی یکتا با حروفِ کوچک و خط‌تیره. Hooks این مقدار را به‌صورتِ agent_type دریافت می‌کنند. نامِ فایل لازم نیست مطابقت داشته باشد
description	بله	اینکه Claude کِی باید کار را به این ساب‌ایجنت بسپارد
tools	خیر	ابزارهایی که ساب‌ایجنت می‌تواند استفاده کند. اگر حذف شود، همه‌ی ابزارها را به ارث می‌برد. برای پیش‌بارگذاریِ Skills در کانتکست، از فیلدِ skills استفاده کن، نه از فهرست‌کردنِ Skill در اینجا
disallowedTools	خیر	ابزارهایی که باید رد شوند، از فهرستِ به‌ارث‌رسیده یا مشخص‌شده حذف می‌شوند
model	خیر	مدلی که باید استفاده شود: sonnet، opus، haiku، fable، یک شناسه‌ی کاملِ مدل (مثلاً claude-opus-4-8)، یا inherit. پیش‌فرض inherit است
permissionMode	خیر	حالتِ مجوز: default، acceptEdits، auto، dontAsk، bypassPermissions، یا plan. برای ساب‌ایجنت‌های پلاگین نادیده گرفته می‌شود
maxTurns	خیر	بیشینه‌ی تعدادِ نوبت‌های ایجنتیک پیش از اینکه ساب‌ایجنت متوقف شود
skills	خیر	Skills که هنگامِ شروع در کانتکستِ ساب‌ایجنت پیش‌بارگذاری می‌شوند. محتوای کاملِ skill تزریق می‌شود، نه فقط توصیفش. ساب‌ایجنت‌ها همچنان می‌توانند skillهای پروژه، کاربر و پلاگینِ فهرست‌نشده را از طریقِ ابزارِ Skill فراخوانی کنند
mcpServers	خیر	سرورهای MCP در دسترسِ این ساب‌ایجنت. هر مدخل یا نامِ یک سرورِ از‌پیش‌پیکربندی‌شده است (مثلاً "slack") یا یک تعریفِ درون‌خطی با نامِ سرور به‌عنوانِ کلید و یک پیکربندیِ کاملِ سرورِ MCP به‌عنوانِ مقدار. برای ساب‌ایجنت‌های پلاگین نادیده گرفته می‌شود
hooks	خیر	Hookهای چرخه‌ی حیات که به این ساب‌ایجنت محدودند. برای ساب‌ایجنت‌های پلاگین نادیده گرفته می‌شوند
memory	خیر	دامنه‌ی حافظه‌ی ماندگار: user، project، یا local. یادگیریِ بین‌نشستی را فعال می‌کند
background	خیر	روی true تنظیم کن تا این ساب‌ایجنت همیشه به‌صورتِ یک کارِ پس‌زمینه اجرا شود. پیش‌فرض: false
effort	خیر	سطحِ effort وقتی این ساب‌ایجنت فعال است. سطحِ effortِ نشست را بازنویسی می‌کند. پیش‌فرض: از نشست به ارث می‌برد. گزینه‌ها: low، medium، high، xhigh، max؛ سطوحِ در دسترس به مدل بستگی دارد
isolation	خیر	روی worktree تنظیم کن تا ساب‌ایجنت در یک git worktreeِ موقت اجرا شود و یک کپیِ ایزوله از مخزن بگیرد که به‌صورتِ پیش‌فرض از شاخه‌ی پیش‌فرضت منشعب می‌شود، نه از HEAD نشستِ والد. اگر ساب‌ایجنت هیچ تغییری ندهد، worktree خودکار پاک‌سازی می‌شود
color	خیر	رنگِ نمایشِ ساب‌ایجنت در فهرستِ کارها و رونوشت. مقادیرِ red، blue، green، yellow، purple، orange، pink یا cyan را می‌پذیرد
initialPrompt	خیر	وقتی این ایجنت به‌عنوانِ ایجنتِ اصلیِ نشست اجرا می‌شود (با --agent یا تنظیمِ agent)، به‌صورتِ اولین نوبتِ کاربر خودکار ثبت می‌شود. Commands و skills پردازش می‌شوند. پیش از هر پرامپتِ ارائه‌شده توسط کاربر قرار می‌گیرد

انتخابِ مدل

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

• نامِ مستعارِ مدل: یکی از نام‌های مستعارِ در دسترس را استفاده کن: sonnet، opus، haiku یا fable
• شناسه‌ی کاملِ مدل: یک شناسه‌ی کاملِ مدل مثلِ claude-opus-4-8 یا claude-sonnet-4-6 را استفاده کن. همان مقادیرِ پرچمِ --model را می‌پذیرد
• inherit: همان مدلِ گفت‌وگوی اصلی را استفاده کن
• حذف‌شده: اگر مشخص نشود، پیش‌فرض inherit است (همان مدلِ گفت‌وگوی اصلی را استفاده می‌کند)

وقتی Claude یک ساب‌ایجنت را فرامی‌خواند، می‌تواند برای آن فراخوانیِ خاص یک پارامترِ model هم پاس بدهد. Claude Code مدلِ ساب‌ایجنت را به این ترتیب حل می‌کند:

1. متغیرِ محیطیِ CLAUDE_CODE_SUBAGENT_MODEL، اگر تنظیم شده باشد
2. پارامترِ modelِ هر فراخوانی
3. frontmatterِ modelِ تعریفِ ساب‌ایجنت
4. مدلِ گفت‌وگوی اصلی

کنترلِ توانایی‌های ساب‌ایجنت

می‌توانی از طریقِ دسترسیِ ابزار، حالت‌های مجوز و قواعدِ شرطی کنترل کنی که ساب‌ایجنت‌ها چه می‌توانند بکنند.

ابزارهای در دسترس

ساب‌ایجنت‌ها به‌صورتِ پیش‌فرض ابزارهای داخلیِ و ابزارهای MCPِ در دسترسِ گفت‌وگوی اصلی را به ارث می‌برند. ابزارهای زیر به UI یا وضعیتِ نشستِ گفت‌وگوی اصلی وابسته‌اند و برای ساب‌ایجنت‌ها در دسترس نیستند، حتی وقتی در فیلدِ tools فهرست شوند:

• AskUserQuestion
• EnterPlanMode
• ExitPlanMode، مگر اینکه permissionModeِ ساب‌ایجنت برابرِ plan باشد
• ScheduleWakeup
• WaitForMcpServers

برای محدودکردنِ ابزارها، یا از فیلدِ tools (فهرستِ مجاز) یا از فیلدِ disallowedTools (فهرستِ ممنوع) استفاده کن. این نمونه از tools استفاده می‌کند تا فقط Read، Grep، Glob و Bash را مجاز کند. ساب‌ایجنت نمی‌تواند فایل ویرایش کند، فایل بنویسد، یا از هیچ ابزارِ MCP استفاده کند:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

این نمونه از disallowedTools استفاده می‌کند تا همه‌ی ابزارهای گفت‌وگوی اصلی جز Write و Edit را به ارث ببرد. ساب‌ایجنت Bash، ابزارهای MCP و باقیِ همه‌چیز را نگه می‌دارد:

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

اگر هر دو تنظیم شوند، اول disallowedTools اعمال می‌شود، بعد tools در برابرِ مخزنِ باقی‌مانده حل می‌شود. ابزاری که در هر دو فهرست شده باشد حذف می‌شود.

محدودکردنِ ساب‌ایجنت‌هایی که می‌توان ایجاد کرد

وقتی یک ایجنت با claude --agent به‌عنوانِ نخِ اصلی اجرا می‌شود، می‌تواند با ابزارِ Agent ساب‌ایجنت ایجاد کند. برای محدودکردنِ اینکه چه انواعِ ساب‌ایجنتی می‌تواند ایجاد کند، از نحوِ Agent(agent_type) در فیلدِ tools استفاده کن.

یادداشت

در نسخه‌ی 2.1.63، ابزارِ Task به Agent تغییرِ نام داد. ارجاع‌های موجودِ Task(...) در تنظیمات و تعریف‌های ایجنت همچنان به‌عنوانِ نامِ مستعار کار می‌کنند.

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

این یک فهرستِ مجاز است: فقط ساب‌ایجنت‌های worker و researcher را می‌توان ایجاد کرد. اگر ایجنت بخواهد هر نوعِ دیگری را ایجاد کند، درخواست شکست می‌خورد و ایجنت فقط انواعِ مجاز را در پرامپتش می‌بیند. برای مسدودکردنِ ایجنت‌های مشخص ضمنِ مجازبودنِ باقی، به‌جای آن از permissions.deny استفاده کن.

برای مجازکردنِ ایجادِ هر ساب‌ایجنتی بدونِ محدودیت، از Agent بدونِ پرانتز استفاده کن:

tools: Agent, Read, Bash

اگر Agent به‌کل از فهرستِ tools حذف شود، ایجنت نمی‌تواند هیچ ساب‌ایجنتی ایجاد کند.

نحوِ فهرستِ مجازِ Agent(agent_type) فقط برای یک ایجنت که با claude --agent به‌عنوانِ نخِ اصلی اجرا می‌شود اعمال می‌شود. در تعریفِ یک ساب‌ایجنت، فهرست‌کردنِ Agent در tools به آن ساب‌ایجنت اجازه می‌دهد ساب‌ایجنت‌های تودرتو ایجاد کند، اما هر فهرستِ نوع درونِ پرانتز نادیده گرفته می‌شود.

محدودکردنِ دامنه‌ی سرورهای MCP به یک ساب‌ایجنت

از فیلدِ mcpServers استفاده کن تا به یک ساب‌ایجنت دسترسی به سرورهای MCPای بدهی که در گفت‌وگوی اصلی در دسترس نیستند. سرورهای درون‌خطیِ تعریف‌شده در اینجا وقتی ساب‌ایجنت شروع می‌شود وصل و وقتی تمام می‌شود قطع می‌شوند. ارجاع‌های رشته‌ای اتصالِ نشستِ والد را به اشتراک می‌گذارند.

یادداشت

فیلدِ mcpServers در هر دو زمینه‌ای که یک فایلِ ایجنت می‌تواند اجرا شود اعمال می‌شود:

• به‌عنوانِ یک ساب‌ایجنت، که از طریقِ ابزارِ Agent یا یک @-mention ایجاد می‌شود
• به‌عنوانِ نشستِ اصلی، که با --agent یا تنظیمِ agent راه‌اندازی می‌شود

وقتی ایجنت نشستِ اصلی است، تعریف‌های سرورِ درون‌خطی هنگامِ شروع کنارِ سرورهای .mcp.json و فایل‌های تنظیمات وصل می‌شوند.

هر مدخلِ فهرست یا یک تعریفِ سرورِ درون‌خطی است یا یک رشته که به یک سرورِ MCPِ از‌پیش‌پیکربندی‌شده در نشستت ارجاع می‌دهد:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

تعریف‌های درون‌خطی از همان طرح‌واره‌ی مدخل‌های سرورِ .mcp.json استفاده می‌کنند (stdio، http، sse، ws)، که با نامِ سرور کلید می‌خورند.

برای اینکه یک سرورِ MCP را به‌کل از گفت‌وگوی اصلی بیرون نگه داری و از مصرفِ کانتکست توسطِ توصیفِ ابزارهایش در آنجا جلوگیری کنی، آن را به‌جای .mcp.json در اینجا به‌صورتِ درون‌خطی تعریف کن. ساب‌ایجنت ابزارها را می‌گیرد؛ گفت‌وگوی والد نمی‌گیرد.

از نسخه‌ی v2.1.153، محدودیت‌های MCP که بر نشستِ اصلی اعمال می‌شوند، سرورهای اعلام‌شده در frontmatterِ ساب‌ایجنت را هم پوشش می‌دهند:

• --strict-mcp-config و --bare
• پیکربندیِ MCPِ مدیریت‌شده‌ی سازمانی
• سیاست‌های allowedMcpServers و deniedMcpServers

وقتی یکی از این‌ها یک سرور را مسدود می‌کند، Claude Code آن را رد می‌کند و هشداری نشان می‌دهد که سرورهای مسدودشده را نام می‌برد.

محدودیت‌های تنظیماتِ مدیریت‌شده بر هر ساب‌ایجنتی صرف‌نظر از نحوه‌ی تعریفش اعمال می‌شوند. --strict-mcp-config سرورهایی را که به‌صورتِ درون‌خطی از طریقِ --agents یا گزینه‌ی agentsِ SDK پاس می‌دهی فیلتر نمی‌کند، چون آن‌ها ورودیِ صریحِ فراخواننده‌اند.

حالت‌های مجوز

فیلدِ permissionMode کنترل می‌کند که ساب‌ایجنت چطور با درخواست‌های مجوز برخورد کند. ساب‌ایجنت‌ها زمینه‌ی مجوز را از گفت‌وگوی اصلی به ارث می‌برند و می‌توانند حالت را بازنویسی کنند، جز وقتی که حالتِ والد به‌شرحِ زیر اولویت دارد.

حالت	رفتار
default	بررسیِ استانداردِ مجوز با درخواست
acceptEdits	پذیرشِ خودکارِ ویرایش‌های فایل و دستورهای رایجِ فایل‌سیستم برای مسیرهای درونِ دایرکتوریِ کاری یا additionalDirectories
auto	حالتِ خودکار: یک طبقه‌بندِ پس‌زمینه دستورها و نوشتن‌ها در دایرکتوری‌های محافظت‌شده را بازبینی می‌کند
dontAsk	ردِ خودکارِ درخواست‌های مجوز (ابزارهای صریحاً مجاز همچنان کار می‌کنند)
bypassPermissions	رد کردنِ درخواست‌های مجوز
plan	حالتِ planning (اکتشافِ فقط‌خواندنی)

احتیاط

از bypassPermissions با احتیاط استفاده کن. این حالت درخواست‌های مجوز را رد می‌کند و به ساب‌ایجنت اجازه می‌دهد عملیات را بدونِ تأیید اجرا کند، از جمله نوشتن در .git، .config/git، .claude، .vscode، .idea، .husky، .cargo، .devcontainer، .yarn و .mvn. قواعدِ صریحِ ask و حذف‌هایی در ریشه و دایرکتوریِ خانه مثلِ rm -rf / همچنان درخواستِ تأیید می‌کنند. برای جزئیات حالت‌های مجوز را ببین.

اگر والد از bypassPermissions یا acceptEdits استفاده کند، این اولویت دارد و قابلِ بازنویسی نیست. اگر والد از حالتِ خودکار استفاده کند، ساب‌ایجنت حالتِ خودکار را به ارث می‌برد و هر permissionModeای در frontmatterش نادیده گرفته می‌شود: طبقه‌بند فراخوانی‌های ابزارِ ساب‌ایجنت را با همان قواعدِ مسدودسازی و مجازِ نشستِ والد ارزیابی می‌کند.

پیش‌بارگذاریِ skills در ساب‌ایجنت‌ها

از فیلدِ skills استفاده کن تا محتوای skill را هنگامِ شروع در کانتکستِ یک ساب‌ایجنت تزریق کنی. این به ساب‌ایجنت دانشِ حوزه‌ای می‌دهد بدونِ اینکه لازم باشد حین اجرا skillها را کشف و بارگذاری کند.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

محتوای کاملِ هر skillِ فهرست‌شده هنگامِ شروع در کانتکستِ ساب‌ایجنت تزریق می‌شود. این فیلد کنترل می‌کند که کدام skillها پیش‌بارگذاری شوند، نه اینکه ساب‌ایجنت به کدام skillها دسترسی دارد: بدونِ آن، ساب‌ایجنت همچنان می‌تواند حین اجرا skillهای پروژه، کاربر و پلاگین را از طریقِ ابزارِ Skill کشف و فراخوانی کند. برای جلوگیریِ کاملِ ساب‌ایجنت از فراخوانیِ skillها، Skill را از فهرستِ tools حذف کن یا آن را به disallowedTools اضافه کن.

نمی‌توانی skillهایی را پیش‌بارگذاری کنی که disable-model-invocation: true دارند، چون پیش‌بارگذاری از همان مجموعه‌ای می‌کشد که Claude می‌تواند فراخوانی کند. اگر یک skillِ فهرست‌شده موجود نباشد یا غیرفعال باشد، Claude Code آن را رد می‌کند و یک هشدار در لاگِ دیباگ ثبت می‌کند.

یادداشت

این برعکسِ اجرای یک skill در یک ساب‌ایجنت است. با skills در یک ساب‌ایجنت، ساب‌ایجنت پرامپتِ سیستمی را کنترل می‌کند و محتوای skill را بارگذاری می‌کند. با context: fork در یک skill، محتوای skill در ایجنتی که مشخص می‌کنی تزریق می‌شود. هر دو از یک سیستمِ زیرین استفاده می‌کنند.

فعال‌کردنِ حافظه‌ی ماندگار

فیلدِ memory به ساب‌ایجنت یک دایرکتوریِ ماندگار می‌دهد که در طولِ گفت‌وگوها باقی می‌ماند. ساب‌ایجنت از این دایرکتوری برای انباشتِ دانش در طولِ زمان استفاده می‌کند، مثلِ الگوهای کدبیس، بینش‌های دیباگ و تصمیم‌های معماری.

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

دامنه را براساسِ اینکه حافظه چقدر گسترده باید اعمال شود انتخاب کن:

دامنه	محل	استفاده کن وقتی
user	~/.claude/agent-memory/<name-of-agent>/	ساب‌ایجنت باید آموخته‌ها را در همه‌ی پروژه‌ها به‌خاطر بسپارد
project	.claude/agent-memory/<name-of-agent>/	دانشِ ساب‌ایجنت مختصِ پروژه است و از طریقِ کنترلِ نسخه قابلِ اشتراک است
local	.claude/agent-memory-local/<name-of-agent>/	دانشِ ساب‌ایجنت مختصِ پروژه است اما نباید به کنترلِ نسخه سپرده شود

وقتی حافظه فعال است:

• پرامپتِ سیستمیِ ساب‌ایجنت دستورهای خواندن از و نوشتن در دایرکتوریِ حافظه را شامل می‌شود.
• پرامپتِ سیستمیِ ساب‌ایجنت همچنین ۲۰۰ خطِ اول یا ۲۵ کیلوبایتِ اولِ MEMORY.md در دایرکتوریِ حافظه را شامل می‌شود، هرکدام که زودتر برسد، با دستورهایی برای مرتب‌سازیِ MEMORY.md اگر از آن حد فراتر رود.
• ابزارهای Read، Write و Edit خودکار فعال می‌شوند تا ساب‌ایجنت بتواند فایل‌های حافظه‌اش را مدیریت کند.

نکته‌های حافظه‌ی ماندگار

• project دامنه‌ی پیش‌فرضِ توصیه‌شده است. دانشِ ساب‌ایجنت را از طریقِ کنترلِ نسخه قابلِ اشتراک می‌کند. وقتی دانشِ ساب‌ایجنت به‌طورِ گسترده در پروژه‌ها کاربرد دارد از user استفاده کن، یا وقتی دانش نباید به کنترلِ نسخه سپرده شود از local استفاده کن.

• از ساب‌ایجنت بخواه پیش از شروعِ کار حافظه‌اش را مشورت کند: “این PR را بازبینی کن، و حافظه‌ات را برای الگوهایی که قبلاً دیده‌ای بررسی کن.”

• از ساب‌ایجنت بخواه پس از تکمیلِ یک کار حافظه‌اش را به‌روز کند: “حالا که تمام کردی، آنچه آموختی را در حافظه‌ات ذخیره کن.” با گذرِ زمان، این یک پایگاهِ دانش می‌سازد که ساب‌ایجنت را مؤثرتر می‌کند.

• دستورهای حافظه را مستقیم در فایلِ markdownِ ساب‌ایجنت بگنجان تا فعالانه پایگاهِ دانشِ خودش را نگه دارد:

  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.

قواعدِ شرطی با hooks

برای کنترلِ پویاتر روی استفاده از ابزار، از hookهای PreToolUse استفاده کن تا عملیات را پیش از اجرا اعتبارسنجی کنی. این وقتی مفید است که لازم داری بعضی عملیاتِ یک ابزار را مجاز کنی ضمنِ مسدودکردنِ بقیه.

این نمونه یک ساب‌ایجنت می‌سازد که فقط کوئری‌های فقط‌خواندنیِ پایگاه‌داده را مجاز می‌کند. hookِ PreToolUse اسکریپتِ مشخص‌شده در command را پیش از اجرای هر دستورِ Bash اجرا می‌کند:

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code ورودیِ hook را به‌صورتِ JSON از طریقِ stdin به دستورهای hook پاس می‌دهد. اسکریپتِ اعتبارسنجی این JSON را می‌خواند، دستورِ Bash را استخراج می‌کند و با کدِ ۲ خارج می‌شود تا عملیاتِ نوشتن را مسدود کند:

./scripts/validate-readonly-query.sh

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

برای طرح‌واره‌ی کاملِ ورودی ورودیِ Hook و برای اینکه ببینی کدهای خروج چطور بر رفتار اثر می‌گذارند کدهای خروج را ببین. روی Windows، اسکریپت‌های hook را در PowerShell بنویس و shell: powershell را به مدخلِ hook اضافه کن، همان‌طور که در اجرای hookها در PowerShell نشان داده شده.

غیرفعال‌کردنِ ساب‌ایجنت‌های مشخص

می‌توانی Claude را از استفاده از ساب‌ایجنت‌های مشخص بازداری، با افزودنِ آن‌ها به آرایه‌ی deny در تنظیماتت. از قالبِ Agent(subagent-name) استفاده کن که در آن subagent-name با فیلدِ name ساب‌ایجنت مطابقت دارد.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

این هم برای ساب‌ایجنت‌های توکار و هم سفارشی کار می‌کند. می‌توانی از پرچمِ CLIِ --disallowedTools هم استفاده کنی:

claude --disallowedTools "Agent(Explore)"

برای جزئیاتِ بیشتر درباره‌ی قواعدِ مجوز مستنداتِ Permissions را ببین.

تعریفِ hooks برای ساب‌ایجنت‌ها

ساب‌ایجنت‌ها می‌توانند hooksای تعریف کنند که در طولِ چرخه‌ی حیاتِ ساب‌ایجنت اجرا شوند. دو راه برای پیکربندیِ hookها وجود دارد:

1. در frontmatterِ ساب‌ایجنت: hookهایی تعریف کن که فقط وقتی آن ساب‌ایجنت فعال است اجرا شوند
2. در settings.json: hookهایی تعریف کن که در نشستِ اصلی هنگامِ شروع یا توقفِ ساب‌ایجنت‌ها اجرا شوند

Hookها در frontmatterِ ساب‌ایجنت

hookها را مستقیم در فایلِ markdownِ ساب‌ایجنت تعریف کن. این hookها فقط وقتی آن ساب‌ایجنتِ خاص فعال است اجرا می‌شوند و وقتی تمام می‌شود پاک‌سازی می‌شوند.

یادداشت

hookهای frontmatter وقتی شلیک می‌شوند که ایجنت به‌عنوانِ یک ساب‌ایجنت از طریقِ ابزارِ Agent یا یک @-mention ایجاد شود، و وقتی ایجنت به‌عنوانِ نشستِ اصلی از طریقِ --agent یا تنظیمِ agent اجرا شود. در حالتِ نشستِ اصلی آن‌ها کنارِ هر hookِ تعریف‌شده در settings.json اجرا می‌شوند.

همه‌ی رویدادهای hook پشتیبانی می‌شوند. رایج‌ترین رویدادها برای ساب‌ایجنت‌ها این‌هایند:

رویداد	ورودیِ matcher	کِی شلیک می‌شود
PreToolUse	نامِ ابزار	پیش از استفاده‌ی ساب‌ایجنت از یک ابزار
PostToolUse	نامِ ابزار	پس از استفاده‌ی ساب‌ایجنت از یک ابزار
Stop	(هیچ)	وقتی ساب‌ایجنت تمام می‌شود (هنگامِ اجرا به SubagentStop تبدیل می‌شود)

این نمونه دستورهای Bash را با hookِ PreToolUse اعتبارسنجی می‌کند و پس از ویرایشِ فایل‌ها با PostToolUse یک linter اجرا می‌کند:

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

وقتی ایجنت به‌عنوانِ یک ساب‌ایجنت فراخوانی می‌شود، hookهای Stop در frontmatter خودکار به رویدادهای SubagentStop تبدیل می‌شوند.

hookهای سطحِ پروژه برای رویدادهای ساب‌ایجنت

hookهایی را در settings.json پیکربندی کن که به رویدادهای چرخه‌ی حیاتِ ساب‌ایجنت در نشستِ اصلی پاسخ دهند.

رویداد	ورودیِ matcher	کِی شلیک می‌شود
SubagentStart	نامِ نوعِ ایجنت	وقتی یک ساب‌ایجنت اجرا را آغاز می‌کند
SubagentStop	نامِ نوعِ ایجنت	وقتی یک ساب‌ایجنت کامل می‌شود

هر دو رویداد از matcherها پشتیبانی می‌کنند تا انواعِ ایجنتِ مشخص را با نام هدف بگیرند. این نمونه یک اسکریپتِ راه‌اندازی را فقط وقتی ساب‌ایجنتِ db-agent شروع می‌شود اجرا می‌کند، و یک اسکریپتِ پاک‌سازی را وقتی هر ساب‌ایجنتی متوقف می‌شود:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

برای قالبِ کاملِ پیکربندیِ hook Hooks را ببین.

کار با ساب‌ایجنت‌ها

درکِ سپردنِ خودکار

Claude کارها را خودکار براساسِ توصیفِ کار در درخواستت، فیلدِ description در پیکربندیِ ساب‌ایجنت‌ها و کانتکستِ جاری می‌سپارد. برای تشویقِ سپردنِ فعالانه، عبارت‌هایی مثلِ “use proactively” را در فیلدِ description ساب‌ایجنتت بگنجان.

فراخوانیِ صریحِ ساب‌ایجنت‌ها

وقتی سپردنِ خودکار کافی نیست، می‌توانی خودت یک ساب‌ایجنت درخواست کنی. سه الگو از یک پیشنهادِ یک‌باره تا یک پیش‌فرضِ سراسرِ نشست تشدید می‌شوند:

• زبانِ طبیعی: ساب‌ایجنت را در پرامپتت نام ببر؛ Claude تصمیم می‌گیرد کار را بسپارد یا نه
• @-mention: تضمین می‌کند که ساب‌ایجنت برای یک کار اجرا شود
• سراسرِ نشست: کلِ نشست از پرامپتِ سیستمی، محدودیت‌های ابزار و مدلِ آن ساب‌ایجنت از طریقِ پرچمِ --agent یا تنظیمِ agent استفاده می‌کند

برای زبانِ طبیعی، نحوِ خاصی نیست. ساب‌ایجنت را نام ببر و Claude معمولاً کار را می‌سپارد:

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

به ساب‌ایجنت @-mention بزن. @ را تایپ کن و ساب‌ایجنت را از فهرستِ پیش‌بین انتخاب کن، همان‌طور که به فایل‌ها @-mention می‌زنی. این تضمین می‌کند که همان ساب‌ایجنتِ مشخص اجرا شود، نه اینکه انتخاب به Claude واگذار شود:

@"code-reviewer (agent)" look at the auth changes

پیامِ کاملت همچنان به Claude می‌رود، که پرامپتِ کارِ ساب‌ایجنت را براساسِ آنچه خواستی می‌نویسد. @-mention کنترل می‌کند که Claude کدام ساب‌ایجنت را فرامی‌خواند، نه اینکه چه پرامپتی دریافت می‌کند.

ساب‌ایجنت‌هایی که یک پلاگینِ فعال فراهم می‌کند با نامِ دامنه‌دارشان در فهرستِ پیش‌بین ظاهر می‌شوند، مثلِ my-plugin:code-reviewer یا my-plugin:review:security وقتی پلاگین ایجنت‌ها را در زیرپوشه‌ها سامان می‌دهد. ساب‌ایجنت‌های پس‌زمینه‌ی نام‌دارِ در‌حال‌اجرا در نشست هم در فهرستِ پیش‌بین ظاهر می‌شوند و وضعیتشان را کنارِ نام نشان می‌دهند. می‌توانی mention را بدونِ استفاده از انتخابگر دستی هم تایپ کنی: @agent-<name> برای ساب‌ایجنت‌های محلی، یا @agent- به‌علاوه‌ی نامِ دامنه‌دار برای ساب‌ایجنت‌های پلاگین، مثلاً @agent-my-plugin:code-reviewer.

کلِ نشست را به‌عنوانِ یک ساب‌ایجنت اجرا کن. --agent <name> را پاس بده تا نشستی شروع کنی که در آن خودِ نخِ اصلی پرامپتِ سیستمی، محدودیت‌های ابزار و مدلِ آن ساب‌ایجنت را به‌عهده می‌گیرد:

claude --agent code-reviewer

پرامپتِ سیستمیِ ساب‌ایجنت به‌طورِ کامل جایگزینِ پرامپتِ سیستمیِ پیش‌فرضِ Claude Code می‌شود، درست همان‌طور که --system-prompt می‌کند. فایل‌های CLAUDE.md و حافظه‌ی پروژه همچنان از طریقِ جریانِ عادیِ پیام بارگذاری می‌شوند. نامِ ایجنت به‌صورتِ @<name> در سرتیترِ شروع ظاهر می‌شود تا بتوانی فعال‌بودنش را تأیید کنی.

این هم با ساب‌ایجنت‌های توکار و هم سفارشی کار می‌کند، و انتخاب وقتی نشست را از سر می‌گیری پایدار می‌ماند.

برای یک ساب‌ایجنتِ فراهم‌شده توسطِ پلاگین، می‌توانی فقط نامِ ایجنت را پاس بدهی و Claude Code آن را پیدا می‌کند:

claude --agent security-reviewer

اگر چند پلاگین ایجنت‌هایی با نامِ یکسان فراهم کنند، نامِ دامنه‌دار را پاس بده تا ابهام برطرف شود:

claude --agent my-plugin:security-reviewer

اگر پلاگین ایجنت را در زیرپوشه‌ای از دایرکتوریِ agents/ خود قرار دهد، زیرپوشه را در نامِ دامنه‌دار بگنجان، مثلاً claude --agent my-plugin:review:security.

برای اینکه آن را پیش‌فرضِ هر نشستی در یک پروژه کنی، agent را در .claude/settings.json تنظیم کن:

{
  "agent": "code-reviewer"
}

اگر هر دو حاضر باشند، پرچمِ CLI بر تنظیم اولویت دارد.

اجرای ساب‌ایجنت‌ها در پیش‌زمینه یا پس‌زمینه

ساب‌ایجنت‌ها می‌توانند در پیش‌زمینه (مسدودکننده) یا پس‌زمینه (هم‌زمان) اجرا شوند:

• ساب‌ایجنت‌های پیش‌زمینه گفت‌وگوی اصلی را تا تکمیل مسدود می‌کنند. درخواست‌های مجوز همان‌طور که پیش می‌آیند به تو پاس داده می‌شوند.
• ساب‌ایجنت‌های پس‌زمینه هم‌زمان اجرا می‌شوند درحالی‌که تو به کار ادامه می‌دهی. آن‌ها با مجوزهای پیش‌تر اعطاشده در نشست اجرا می‌شوند و هر فراخوانیِ ابزاری را که در غیرِ این صورت درخواستِ تأیید می‌کرد خودکار رد می‌کنند. اگر یک ساب‌ایجنتِ پس‌زمینه نیاز داشته باشد سؤالِ توضیحی بپرسد، آن فراخوانیِ ابزار شکست می‌خورد اما ساب‌ایجنت ادامه می‌دهد.

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

Claude براساسِ کار تصمیم می‌گیرد ساب‌ایجنت‌ها را در پیش‌زمینه اجرا کند یا پس‌زمینه. می‌توانی همچنین:

• از Claude بخواهی “این را در پس‌زمینه اجرا کن”
• Ctrl+B را بزنی تا یک کارِ در‌حال‌اجرا را به پس‌زمینه ببری

برای غیرفعال‌کردنِ کاملِ قابلیتِ کارِ پس‌زمینه، متغیرِ محیطیِ CLAUDE_CODE_DISABLE_BACKGROUND_TASKS را روی 1 تنظیم کن. متغیرهای محیطی را ببین.

وقتی CLAUDE_CODE_FORK_SUBAGENT روی 1 تنظیم شود، هر ایجادِ ساب‌ایجنت صرف‌نظر از فیلدِ background در پس‌زمینه اجرا می‌شود. Forkها همچنان درخواست‌های مجوز را همان‌طور که پیش می‌آیند در ترمینالت نمایان می‌کنند؛ ساب‌ایجنت‌های نام‌دار هر چیزی را که درخواستِ تأیید می‌کرد خودکار رد می‌کنند، همان‌طور که بالاتر توصیف شد.

الگوهای رایج

ایزوله‌کردنِ عملیاتِ پرحجم

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

Use a subagent to run the test suite and report only the failing tests with their error messages

اجرای تحقیقِ موازی

برای بررسی‌های مستقل، چند ساب‌ایجنت ایجاد کن تا هم‌زمان کار کنند:

Research the authentication, database, and API modules in parallel using separate subagents

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

احتیاط

وقتی ساب‌ایجنت‌ها تمام می‌شوند، نتایجشان به گفت‌وگوی اصلی‌ات برمی‌گردد. اجرای ساب‌ایجنت‌های زیاد که هرکدام نتایجِ مفصل برمی‌گردانند می‌تواند کانتکستِ قابل‌توجهی مصرف کند.

برای کارهایی که به موازی‌سازیِ پایدار نیاز دارند یا از پنجره‌ی کانتکستت فراتر می‌روند، agent teams به هر کارگر کانتکستِ مستقلِ خودش را می‌دهد.

زنجیره‌کردنِ ساب‌ایجنت‌ها

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

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

انتخاب بینِ ساب‌ایجنت‌ها و گفت‌وگوی اصلی

از گفت‌وگوی اصلی استفاده کن وقتی:

• کار به رفت‌وبرگشتِ مکرر یا پالایشِ تکرارشونده نیاز دارد
• چند فاز کانتکستِ قابل‌توجهی به اشتراک می‌گذارند (برنامه‌ریزی ← پیاده‌سازی ← تست)
• داری یک تغییرِ سریع و هدفمند می‌دهی
• تأخیر مهم است. ساب‌ایجنت‌ها از نو شروع می‌کنند و ممکن است برای جمع‌آوریِ کانتکست زمان لازم داشته باشند

از ساب‌ایجنت‌ها استفاده کن وقتی:

• کار خروجیِ پرحجمی تولید می‌کند که در کانتکستِ اصلی‌ات لازم نداری
• می‌خواهی محدودیت‌ها یا مجوزهای مشخصِ ابزار را اعمال کنی
• کار خودبسنده است و می‌تواند یک خلاصه برگرداند

وقتی پرامپت‌ها یا ورک‌فلوهای قابلِ‌بازاستفاده می‌خواهی که در کانتکستِ گفت‌وگوی اصلی اجرا شوند به‌جای کانتکستِ ایزوله‌ی ساب‌ایجنت، به‌جای آن Skills را در نظر بگیر.

برای یک سؤالِ سریع درباره‌ی چیزی که از پیش در گفت‌وگویت هست، به‌جای یک ساب‌ایجنت از /btw استفاده کن. کلِ کانتکستت را می‌بیند اما هیچ دسترسیِ ابزاری ندارد، و پاسخ به‌جای افزوده‌شدن به تاریخچه، دور انداخته می‌شود.

ایجادِ ساب‌ایجنت‌های تودرتو

{/* min-version: 2.1.172 */}از نسخه‌ی Claude Code v2.1.172، یک ساب‌ایجنت می‌تواند ساب‌ایجنت‌های خودش را ایجاد کند. این را وقتی استفاده کن که یک کارِ سپرده‌شده خودش به زیرکارهای موازی تقسیم می‌شود، مثلِ یک ساب‌ایجنتِ بازبین که برای هر یافته یک تأییدکننده اعزام می‌کند، تا خروجیِ میانی هرگز به گفت‌وگوی اصلی‌ات نرسد. فقط خلاصه‌ی ساب‌ایجنتِ سطحِ بالا به تو برمی‌گردد.

یک ساب‌ایجنتِ تودرتو دقیقاً مثلِ یک ساب‌ایجنتِ سطحِ بالا پیکربندی می‌شود و از همان دامنه‌ها حل می‌شود. پنلِ ساب‌ایجنت زیرِ ورودیِ پرامپت کلِ درخت را نشان می‌دهد: هر ردیف یک شمارشِ (+N) از نوادگان نشان می‌دهد، و بازکردنِ یک ردیف فرزندانِ مستقیمِ آن ساب‌ایجنت را با مسیری برگشت به main نشان می‌دهد. تبِ Running در /agents ساب‌ایجنت‌های در‌حال‌اجرا را به‌صورتِ فهرستی مسطح فهرست می‌کند.

عمق به‌صورتِ تعدادِ سطوحِ ساب‌ایجنتِ زیرِ گفت‌وگوی اصلی شمرده می‌شود، صرف‌نظر از اینکه هر سطح در پیش‌زمینه یا پس‌زمینه اجرا شود:

• ساب‌ایجنت‌های پیش‌زمینه: می‌توانند در هر عمقی ایجاد شوند. هر سطح والدش را تا بازگشت مسدود می‌کند، پس زنجیره خودمحدودکننده است: گفت‌وگوی اصلی منتظرِ کلِ زنجیره می‌ماند.
• ساب‌ایجنت‌های پس‌زمینه: یک ساب‌ایجنتِ پس‌زمینه در عمقِ پنج ابزارِ Agent را دریافت نمی‌کند و نمی‌تواند بیشتر ایجاد کند. این محدودیت ثابت و غیرقابلِ‌پیکربندی است، و برای جلوگیری از درخت‌های هم‌زمانِ افسارگسیخته وجود دارد.

برای جلوگیریِ یک ساب‌ایجنتِ خاص از ایجادِ دیگران، Agent را از فهرستِ tools آن حذف کن یا آن را به disallowedTools اضافه کن.

یک fork همچنان نمی‌تواند fork دیگری ایجاد کند. می‌تواند انواعِ دیگرِ ساب‌ایجنت را ایجاد کند، و آن‌ها به‌سمتِ محدودیتِ عمق به‌حساب می‌آیند.

مدیریتِ کانتکستِ ساب‌ایجنت

چه چیزهایی در شروع بارگذاری می‌شوند

هر ساب‌ایجنت با یک پنجره‌ی کانتکستِ تازه و ایزوله شروع می‌شود. تاریخچه‌ی گفت‌وگویت، skillهایی که از پیش فراخوانده‌ای، یا فایل‌هایی که Claude از پیش خوانده را نمی‌بیند. Claude یک پیامِ سپردن می‌سازد که کار را خلاصه می‌کند، و ساب‌ایجنت از آنجا کار می‌کند. استثنا یک fork است، که به‌جای شروعِ تازه گفت‌وگوی والد را به ارث می‌برد.

کانتکستِ اولیه‌ی یک ساب‌ایجنتِ غیر‌fork شاملِ این‌هاست:

• پرامپتِ سیستمی: پرامپتِ خودِ ایجنت به‌علاوه‌ی جزئیاتِ محیطی که Claude Code الحاق می‌کند، نه کلِ پرامپتِ سیستمیِ Claude Code. ساب‌ایجنت‌های سفارشی پرامپتشان را در بدنه‌ی markdown یا فیلدِ prompt تعریف می‌کنند. ایجنت‌های توکار پرامپت‌های از‌پیش‌تعریف‌شده دارند.
• پیامِ کار: پرامپتِ سپردن که Claude هنگامِ واگذاریِ کار می‌نویسد.
• CLAUDE.md و حافظه: هر سطحی از سلسله‌مراتبِ حافظه که گفت‌وگوی اصلی بارگذاری می‌کند، شاملِ ~/.claude/CLAUDE.md، قواعدِ پروژه، CLAUDE.local.md و فایل‌های سیاستِ مدیریت‌شده. ایجنت‌های توکارِ Explore و Plan این را نادیده می‌گیرند.
• وضعیتِ Git: یک عکسِ‌فوری که در شروعِ نشستِ والد گرفته شده. وقتی دایرکتوریِ کاری یک مخزنِ Git نیست یا وقتی includeGitInstructions برابرِ false است، غایب است. Explore و Plan صرف‌نظر از همه‌چیز این را نادیده می‌گیرند.
• skillهای پیش‌بارگذاری‌شده: محتوای کاملِ هر skillی که در فیلدِ skills ایجنت نام برده شده. ایجنت‌های توکار skill پیش‌بارگذاری نمی‌کنند.

Explore و Plan تنها ساب‌ایجنت‌هایی‌اند که CLAUDE.md و وضعیتِ git را حذف می‌کنند. هیچ فیلدِ frontmatter یا تنظیمِ هر‌ایجنتی برای تغییرِ اینکه کدام ایجنت‌ها آن‌ها را نادیده بگیرند وجود ندارد.

گفت‌وگوی اصلی نتایجِ Explore و Plan را با کانتکستِ کاملِ CLAUDE.md می‌خواند، پس بیشترِ قواعد لازم نیست به خودِ ساب‌ایجنت برسند. اگر قاعده‌ای حتماً باید برسد، مثلِ “دایرکتوریِ vendor/ را نادیده بگیر”، آن را در پرامپتی که هنگامِ سپردن به Claude می‌دهی دوباره بیان کن.

از سر گرفتنِ ساب‌ایجنت‌ها

هر فراخوانیِ ساب‌ایجنت یک نمونه‌ی جدید با کانتکستِ تازه می‌سازد. برای ادامه‌ی کارِ یک ساب‌ایجنتِ موجود به‌جای شروع از نو، از Claude بخواه از سرش بگیرد.

ساب‌ایجنت‌های از‌سر‌گرفته‌شده تاریخچه‌ی گفت‌وگوی کاملشان را حفظ می‌کنند، شاملِ همه‌ی فراخوانی‌های ابزار، نتایج و استدلال‌های پیشین. ساب‌ایجنت دقیقاً از جایی که متوقف شد ادامه می‌دهد، نه از نو.

وقتی یک ساب‌ایجنت تمام می‌شود، Claude شناسه‌ی ایجنتش را دریافت می‌کند. ایجنت‌های توکارِ Explore و Plan یک‌باره‌اند و هیچ شناسه‌ی ایجنتی برنمی‌گردانند، پس نمی‌توان از سرشان گرفت؛ وقتی نیاز داری کار را ادامه دهی از general-purpose یا یک ساب‌ایجنتِ سفارشی استفاده کن. Claude از ابزارِ SendMessage با شناسه‌ی ایجنت به‌عنوانِ فیلدِ to برای از‌سر‌گرفتنش استفاده می‌کند. ابزارِ SendMessage فقط وقتی در دسترس است که agent teams از طریقِ CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 فعال شده باشد.

برای از سر گرفتنِ یک ساب‌ایجنت، از Claude بخواه کارِ پیشین را ادامه دهد:

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

اگر یک ساب‌ایجنتِ متوقف‌شده یک SendMessage دریافت کند، بدونِ نیاز به یک فراخوانیِ Agent جدید خودکار در پس‌زمینه از سر گرفته می‌شود.

می‌توانی از Claude شناسه‌ی ایجنت را هم بخواهی اگر می‌خواهی صراحتاً به آن ارجاع دهی، یا شناسه‌ها را در فایل‌های رونوشت در ~/.claude/projects/{project}/{sessionId}/subagents/ پیدا کنی. هر رونوشت به‌صورتِ agent-{agentId}.jsonl ذخیره می‌شود.

رونوشت‌های ساب‌ایجنت مستقل از گفت‌وگوی اصلی پایدار می‌مانند:

• فشرده‌سازیِ گفت‌وگوی اصلی: وقتی گفت‌وگوی اصلی فشرده می‌شود، رونوشت‌های ساب‌ایجنت تأثیر نمی‌گیرند. آن‌ها در فایل‌های جداگانه ذخیره می‌شوند.
• پایداریِ نشست: رونوشت‌های ساب‌ایجنت درونِ نشستشان پایدار می‌مانند. می‌توانی پس از ری‌استارتِ Claude Code با از‌سر‌گرفتنِ همان نشست یک ساب‌ایجنت را از سر بگیری.
• پاک‌سازیِ خودکار: رونوشت‌ها براساسِ تنظیمِ cleanupPeriodDays (پیش‌فرض: ۳۰ روز) پاک‌سازی می‌شوند.

فشرده‌سازیِ خودکار

ساب‌ایجنت‌ها از فشرده‌سازیِ خودکار با همان منطقِ گفت‌وگوی اصلی پشتیبانی می‌کنند. فشرده‌سازی تحتِ همان شرایط فعال می‌شود، و CLAUDE_AUTOCOMPACT_PCT_OVERRIDE برای ساب‌ایجنت‌ها هم اعمال می‌شود. برای اینکه ببینی override کِی اثر می‌کند متغیرهای محیطی را ببین.

رویدادهای فشرده‌سازی در فایل‌های رونوشتِ ساب‌ایجنت لاگ می‌شوند:

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

مقدارِ preTokens نشان می‌دهد پیش از وقوعِ فشرده‌سازی چند توکن استفاده شده بود.

Fork کردنِ گفت‌وگوی جاری

یادداشت

ساب‌ایجنت‌های Fork‌شده به Claude Code نسخه‌ی v2.1.117 یا جدیدتر نیاز دارند. {/* min-version: 2.1.161 */}از v2.1.161 دستورِ /fork به‌صورتِ پیش‌فرض فعال است؛ در نسخه‌های قدیمی‌تر به تنظیمِ متغیرِ محیطیِ CLAUDE_CODE_FORK_SUBAGENT روی 1 نیاز دارد. پیش‌فرض‌کردنِ رفتارِ ایجادِ مدل به fork آزمایشی است و ممکن است در نسخه‌های آینده تغییر کند. این پیش‌فرض ممکن است در نشست‌های تعاملی هم به‌عنوانِ بخشی از یک عرضه‌ی مرحله‌ای فعال شود.

یک fork ساب‌ایجنتی است که به‌جای شروعِ تازه کلِ گفت‌وگوی تا‌کنون را به ارث می‌برد. این ایزولاسیونِ ورودی‌ای را که ساب‌ایجنت‌ها در غیرِ این صورت فراهم می‌کنند کنار می‌گذارد: یک fork همان پرامپتِ سیستمی، ابزارها، مدل و تاریخچه‌ی پیامِ نشستِ اصلی را می‌بیند، پس می‌توانی یک کارِ جانبی به آن بدهی بدونِ اینکه دوباره موقعیت را توضیح دهی. فراخوانی‌های ابزارِ خودِ fork همچنان بیرونِ گفت‌وگویت می‌مانند و فقط نتیجه‌ی نهایی‌اش برمی‌گردد، پس پنجره‌ی کانتکستِ اصلی‌ات تمیز می‌ماند. وقتی یک ساب‌ایجنتِ نام‌دار به پیش‌زمینه‌ی زیادی نیاز داشته باشد تا مفید باشد، یا وقتی می‌خواهی از یک نقطه‌ی شروعِ یکسان چند رویکرد را موازی امتحان کنی، از یک fork استفاده کن.

برای کنترلِ حالتِ fork صرف‌نظر از عرضه‌ی مرحله‌ای، CLAUDE_CODE_FORK_SUBAGENT را روی 1 تنظیم کن تا صراحتاً فعال شود یا روی 0 تا غیرفعال شود. این متغیر در حالتِ تعاملی و از طریقِ SDK یا claude -p رعایت می‌شود.

فعال‌کردنِ حالتِ fork Claude Code را به دو شکل تغییر می‌دهد:

• Claude هرگاه که در غیرِ این صورت از ساب‌ایجنتِ general-purpose استفاده می‌کرد، یک fork ایجاد می‌کند. ساب‌ایجنت‌های نام‌دار مثلِ Explore همچنان مثلِ قبل ایجاد می‌شوند.
• هر ایجادِ ساب‌ایجنت در پس‌زمینه اجرا می‌شود، چه fork باشد چه یک ساب‌ایجنتِ نام‌دار. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS را روی 1 تنظیم کن تا ایجادها هم‌زمان (synchronous) بمانند.

می‌توانی خودت یک fork را با /fork به‌علاوه‌ی یک دستور شروع کنی، با یا بدونِ تنظیمِ متغیر. Claude Code fork را از اولین کلماتِ دستور نام‌گذاری می‌کند. نمونه‌ی زیر گفت‌وگو را fork می‌کند تا کِیس‌های تست را پیش‌نویس کند درحالی‌که تو در نشستِ اصلی به پیاده‌سازی ادامه می‌دهی:

/fork draft unit tests for the parser changes so far

fork در پنلی زیرِ پرامپتت ظاهر می‌شود و در پس‌زمینه اجرا می‌شود درحالی‌که تو به کار ادامه می‌دهی. وقتی تمام شد، نتیجه‌اش به‌صورتِ یک پیام در گفت‌وگوی اصلی‌ات می‌رسد. بخشِ بعدی کنترل‌های پنل را برای تماشا و هدایتِ forkها حین اجرا پوشش می‌دهد.

مشاهده و هدایتِ forkهای در‌حال‌اجرا

forkهای در‌حال‌اجرا در پنلی زیرِ ورودیِ پرامپت ظاهر می‌شوند، با یک ردیف برای نشستِ اصلی و یک ردیف برای هر fork. از این کلیدها برای کار با پنل استفاده کن:

کلید	کنش
↑ / ↓	جابه‌جایی بینِ ردیف‌ها
Enter	بازکردنِ رونوشتِ forkِ انتخاب‌شده و فرستادنِ پیام‌های پیگیری به آن
x	بستنِ یک forkِ تمام‌شده یا توقفِ یک forkِ در‌حال‌اجرا
Esc	بازگرداندنِ تمرکز به ورودیِ پرامپت

تفاوتِ forkها با ساب‌ایجنت‌های نام‌دار

یک fork هر چیزی را که نشستِ اصلی در لحظه‌ی ایجادش دارد به ارث می‌برد. یک ساب‌ایجنتِ نام‌دار از تعریفِ خودش شروع می‌کند.

	Fork	ساب‌ایجنتِ نام‌دار
کانتکست	تاریخچه‌ی کاملِ گفت‌وگو	کانتکستِ تازه با پرامپتی که پاس می‌دهی
پرامپتِ سیستمی و ابزارها	همان نشستِ اصلی	از فایلِ تعریفِ ساب‌ایجنت
مدل	همان نشستِ اصلی	از فیلدِ modelِ ساب‌ایجنت
مجوزها	درخواست‌ها در ترمینالت نمایان می‌شوند	هنگامِ اجرا در پس‌زمینه خودکار رد می‌شوند
کشِ پرامپت	با نشستِ اصلی به اشتراک گذاشته می‌شود	کشِ جداگانه

چون پرامپتِ سیستمی و تعریف‌های ابزارِ یک fork عیناً با والد یکسان‌اند، اولین درخواستش کشِ پرامپتِ والد را بازاستفاده می‌کند. این forkکردن را برای کارهایی که به همان کانتکست نیاز دارند ارزان‌تر از ایجادِ یک ساب‌ایجنتِ تازه می‌کند.

وقتی Claude از طریقِ ابزارِ Agent یک fork ایجاد می‌کند، می‌تواند isolation: "worktree" را پاس بدهد تا ویرایش‌های فایلِ fork به‌جای checkoutت در یک git worktreeِ جداگانه نوشته شوند.

محدودیت‌ها

تنظیمِ CLAUDE_CODE_FORK_SUBAGENT=1 حالتِ fork را در نشست‌های تعاملی، حالتِ غیرتعاملی و Agent SDK فعال می‌کند؛ تنظیمِ آن روی 0 حالتِ fork را همه‌جا غیرفعال می‌کند، از جمله هر عرضه‌ی سمتِ سرور. یک fork نمی‌تواند forkهای بیشتری ایجاد کند.

نمونه ساب‌ایجنت‌ها

این نمونه‌ها الگوهای مؤثری برای ساختِ ساب‌ایجنت‌ها را نشان می‌دهند. آن‌ها را به‌عنوانِ نقطه‌ی شروع استفاده کن، یا با Claude یک نسخه‌ی سفارشی بساز.

نکته

بهترین شیوه‌ها:

• ساب‌ایجنت‌های متمرکز طراحی کن: هر ساب‌ایجنت باید در یک کارِ خاص برتر باشد
• توصیف‌های مفصل بنویس: Claude از توصیف استفاده می‌کند تا تصمیم بگیرد کِی کار را بسپارد
• دسترسیِ ابزار را محدود کن: فقط مجوزهای لازم را برای امنیت و تمرکز بده
• به کنترلِ نسخه بسپار: ساب‌ایجنت‌های پروژه را با تیمت به اشتراک بگذار

بازبینِ کد (Code reviewer)

یک ساب‌ایجنتِ فقط‌خواندنی که کد را بدونِ تغییردادنش بازبینی می‌کند. این نمونه نشان می‌دهد چطور یک ساب‌ایجنتِ متمرکز با دسترسیِ محدودِ ابزار (بدونِ Edit یا Write) و یک پرامپتِ مفصل طراحی کنی که دقیقاً مشخص می‌کند دنبالِ چه باشد و خروجی را چطور قالب‌بندی کند.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

دیباگر (Debugger)

یک ساب‌ایجنت که هم می‌تواند مسائل را تحلیل کند و هم رفع کند. برخلافِ بازبینِ کد، این یکی Edit را شامل می‌شود چون رفعِ باگ نیازمندِ تغییرِ کد است. پرامپت یک ورک‌فلوی روشن از تشخیص تا تأیید فراهم می‌کند.

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

دانشمندِ داده (Data scientist)

یک ساب‌ایجنتِ مختصِ حوزه برای کارِ تحلیلِ داده. این نمونه نشان می‌دهد چطور برای ورک‌فلوهای تخصصیِ بیرون از کارهای معمولِ کدنویسی ساب‌ایجنت بسازی. صراحتاً model: sonnet را برای تحلیلِ توانمندتر تنظیم می‌کند.

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

اعتبارسنجِ کوئریِ پایگاه‌داده (Database query validator)

یک ساب‌ایجنت که دسترسیِ Bash را اجازه می‌دهد اما دستورها را اعتبارسنجی می‌کند تا فقط کوئری‌های SQLِ فقط‌خواندنی را مجاز کند. این نمونه نشان می‌دهد چطور از hookهای PreToolUse برای اعتبارسنجیِ شرطی استفاده کنی وقتی به کنترلِ ظریف‌تری از آنچه فیلدِ tools فراهم می‌کند نیاز داری.

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

Claude Code ورودیِ hook را به‌صورتِ JSON از طریقِ stdin به دستورهای hook پاس می‌دهد. اسکریپتِ اعتبارسنجی این JSON را می‌خواند، دستورِ در‌حال‌اجرا را استخراج می‌کند و آن را در برابرِ فهرستی از عملیاتِ نوشتنِ SQL بررسی می‌کند. اگر یک عملیاتِ نوشتن تشخیص داده شود، اسکریپت با کدِ ۲ خارج می‌شود تا اجرا را مسدود کند و یک پیامِ خطا را از طریقِ stderr به Claude برمی‌گرداند.

اسکریپتِ اعتبارسنجی را هرجایی در پروژه‌ات بساز. مسیر باید با فیلدِ command در پیکربندیِ hookت مطابقت داشته باشد:

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

روی macOS و Linux، اسکریپت را اجرایی کن:

chmod +x ./scripts/validate-readonly-query.sh

روی Windows، اسکریپتِ اعتبارسنجی را در PowerShell بنویس و shell: powershell را به مدخلِ hook اضافه کن. اجرای hookها در PowerShell را ببین.

hook از طریقِ stdin یک JSON دریافت می‌کند که دستورِ Bash در tool_input.command آن است. کدِ خروجِ ۲ عملیات را مسدود می‌کند و پیامِ خطا را به Claude بازخورد می‌دهد. برای جزئیاتِ کدهای خروج Hooks و برای طرح‌واره‌ی کاملِ ورودی ورودیِ Hook را ببین.

گام‌های بعدی

حالا که ساب‌ایجنت‌ها را می‌فهمی، این قابلیت‌های مرتبط را کاوش کن:

• توزیعِ ساب‌ایجنت‌ها با پلاگین‌ها برای به‌اشتراک‌گذاریِ ساب‌ایجنت‌ها در تیم‌ها یا پروژه‌ها
• اجرای برنامه‌نویسی‌شده‌ی Claude Code با Agent SDK برای CI/CD و اتوماسیون
• استفاده از سرورهای MCP برای دادنِ دسترسیِ ساب‌ایجنت‌ها به ابزارها و داده‌های خارجی