درس ۳ از ۵

ج — Course 3: Introduction to subagents (چهار lecture)

این course در ۲۰ دقیقه در عمق subagent ها فرو می‌رود. اگر در course اول مفهوم را در سطح بالا گرفتید، اینجا می‌آموزید چگونه طراحی، scoping و invocation را به‌درستی انجام دهید.

Lecture 3.1 — subagent ها چه هستند

عنوان اصلی: What are subagents

هدف یادگیری: تعریف subagent و سه مسئله‌ای که حل می‌کند: bloat در context، تمرکز، و scoping permission.

مفاهیم کلیدی: isolated context window, custom system prompt, tool allowlist, Haiku for cost control, single-session (در مقابل agent teams که cross-session هستند).

تعریف رسمی Anthropic: «Subagents are specialized AI assistants that handle specific types of tasks. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.»

مزایای رسمی (verbatim): - Preserve context — کار اصلی session اصلی آلوده نمی‌شود. - Enforce constraints — tool و permission محدود. - Reuse configurations — یک‌بار بنویس، همه‌جا استفاده کن. - Specialize behavior — system prompt اختصاصی. - Control costs — task های ساده را به مدل ارزان‌تر مثل Haiku بسپار.

اگر agent در session های موازی نیاز دارید، باید از agent teams استفاده کنید نه subagent — subagent ها در یک session واحد می‌مانند.

اشتباهات رایج

  • تلاش برای nest کردن subagent در subagent دیگر (پشتیبانی نمی‌شود).
  • استفاده از subagent برای کارهایی که بهتر است agent team باشند (مثلاً سه task کاملاً مستقل که می‌توانند موازی روی repo های جداگانه اجرا شوند).

Lecture 3.2 — ساخت یک subagent

عنوان اصلی: Creating a subagent

هدف یادگیری: استفاده از /agents برای scaffold یا نوشتن دستی فایل markdown.

مفاهیم کلیدی: /agents interactive UI, Library tab, "Generate with Claude", scope (Personal ~/.claude/agents/ vs Project .claude/agents/), tool selection, model selection, color, persistent memory scope (user|project|local).

دستور /agents بزنید → Library → Create new agent. گزینه‌ی «Generate with Claude» را انتخاب کنید و agent را با زبان طبیعی توصیف کنید؛ Claude خودش frontmatter YAML و system prompt را می‌نویسد. tool ها (read-only برای reviewer)، model (Sonnet برای تحلیل، Haiku برای سرعت، Opus برای reasoning سخت) و یک رنگ برای تشخیص در UI انتخاب کنید. با s یا Enter ذخیره کنید، یا e برای save-and-edit.

مثال عملی

---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
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.

اشتباهات رایج

  • نوشتن دستی فایل و انتظار اینکه در همان session بارگذاری شود. فایل‌های دستی در ابتدای session load می‌شوند — باید Claude Code را restart کنید یا دوباره /agents بزنید.

Lecture 3.3 — طراحی subagent موثر

عنوان اصلی: Designing effective subagents

هدف یادگیری: انتخاب درست scope، tools، model و description تا Claude به‌درستی delegate کند.

مفاهیم کلیدی: description-driven delegation ("use proactively"), tool allowlist vs disallowedTools, permissionMode, maxTurns, skills: preload, memory: scope, mcpServers: scoping, isolation: worktree, Agent(agent_type) allowlist, --agent to make it the main session.

فیلد description بزرگ‌ترین تعیین‌کننده‌ی اینکه Claude چه زمانی delegate کند است. عبارت‌هایی مثل «Use proactively after code changes» نرخ delegation را به‌شدت بالا می‌برد.

برای محدودسازی tool: tools: allowlist است؛ disallowedTools: denylist است (اول denylist اعمال، سپس allowlist resolve). از model: haiku برای agent جست‌وجوی ارزان استفاده کنید (همان کاری که agent built-in Explore می‌کند). از isolation: worktree استفاده کنید تا subagent در یک git worktree موقت بماند و نتواند tree اصلی را آلوده کند. از skills: برای preload دانش حوزه‌ای استفاده کنید. از memory: user|project|local برای دادن یک MEMORY.md ماندگار که از session می‌ماند استفاده کنید.

ترتیب resolve مدل (verbatim): CLAUDE_CODE_SUBAGENT_MODEL env → per-invocation model param → subagent frontmatter model → main conversation model.

اشتباهات رایج

نقل قول رسمی: «If the parent uses bypassPermissions or acceptEdits, this takes precedence and cannot be overridden.» — انتظار نداشته باشید subagent در parent با permission باز بتواند سخت‌گیرانه‌تر باشد. چنین چیزی override نمی‌شود.

Lecture 3.4 — استفاده‌ی موثر از subagent ها

عنوان اصلی: Using subagents effectively

هدف یادگیری: invoke صریح در صورت نیاز؛ ترکیب با skill، hook و MCP.

مفاهیم کلیدی: natural-language naming, @agent-<name> mention, --agent <name> whole session, fork-current-conversation pattern, SubagentStart / SubagentStop hooks.

سه سطح escalation:

  1. زبان طبیعی — «Use the code-reviewer subagent» — Claude ممکن است delegate کند.
  2. @agent-code-reviewer — تضمین می‌کند subagent برای task بعدی اجرا شود.
  3. claude --agent code-reviewer — کل session system prompt، tool ها و model آن subagent را می‌گیرد.

از SubagentStart / SubagentStop hook در settings.json برای راه‌اندازی DB connection، log کردن spawn، یا cleanup استفاده کنید. Stop hook در frontmatter یک subagent در runtime به‌صورت خودکار به SubagentStop تبدیل می‌شود.

مثال عملی

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

اشتباهات رایج

نقل قول مستقیم: «وقتی Claude در codebase research می‌کند فایل‌های زیادی می‌خواند، که همگی context شما را مصرف می‌کنند. subagent ها در context window جداگانه اجرا می‌شوند و فقط خلاصه برمی‌گردانند.» در research های بزرگ، استفاده‌ی aggressive از subagent در طول session compounding صرفه‌جویی می‌کند.