الـ subagents بتخلّي Claude يفوّض الشغل لمساعدين AI متخصصين، كل واحد بـ context window خاص بيه وأدوات وsystem prompt. بيمنعوا تلوث السياق في المهام الطويلة، وبيسمحوا بالتنفيذ المتوازي، وبيخلوك تحوّل الخبرة التقنية لـ agents قابلين لإعادة الاستخدام. في الموديول ده، هنغطي إزاي تعمل وتضبط وتستخدم الـ subagents بفعالية.
إنشاء Subagents
الـ subagents هي ملفات markdown بـ YAML frontmatter. ممكن تعرّفها بالـ flag --agents في الـ CLI لجلسة واحدة، أو تحطها في .claude/agents/ لنطاق المشروع (بتتعمل لها commit في git)، أو ~/.claude/agents/ للنطاق الشخصي (كل المشاريع). الـ plugins كمان ممكن تجمّع agents. الأولوية: managed > CLI flag > project > user > plugin. الـ built-in agents ممكن تتخطّى بتسمية custom subagent بنفس الاسم — subagent في نطاق user أو project اسمه Explore بيتخطى على الـ built-in وبيحافظ على الـ model field بتاعه. بدءًا من v2.1.198، أمر /agents ما بفتحش panel — بدلًا من كده بيطبع notice بيوجّهك لموقع ملفات الـ subagents. عشان تنشئ وتعدّل custom subagents، اسأل Claude أو عدّل الملفات مباشرة.
الـ frontmatter بيعرّف هوية الـ agent. محتوى الـ markdown هو الـ system prompt بتاعه — اكتبه كأنك بتعمل briefing لمتخصص:
---
name: security-reviewer
description: Security-focused code reviewer. Use proactively after writing authentication, authorization, or data handling code.
tools: Read, Grep, Glob
---
You are a senior security engineer specializing in application security.
Review priorities:
1. Authentication and authorization flaws
2. Injection vulnerabilities (SQL, XSS, command)
3. Data exposure and sensitive information handling
4. Cryptographic weaknesses
5. Insecure direct object references
For each finding, provide: severity (Critical/High/Medium/Low), location (file:line), description, and a concrete fix with code example.
When invoked: use Grep and Read to inspect recently changed files.الـ tools field بيحدد الأدوات اللي الـ agent يقدر يستعملها. security reviewer محتاج Read وGrep وGlob بس — مفيش وصول للكتابة. implementation agent محتاج كل الأدوات. تقييد الأدوات بيخلّي الـ agent أكتر أمانًا وسلوكه أكتر قابلية للتوقع. لو حذفت tools، الـ agent بيورث كل الأدوات المتاحة.
خيارات الإعداد
بجانب الوصول الأساسي للأدوات، الـ frontmatter بيدعم خيارات قوية. model بيحدد الموديل اللي الـ agent بيستخدمه — haiku للمهام السريعة والخفيفة، sonnet للشغل المتوازن، أو opus للتفكير المعقد. كمان ممكن تستخدم inherit عشان يورث موديل الـ parent. effort بيتحكم في عمق التحليل على الموديلات المدعومة، بقيم low وmedium وhigh وxhigh وmax. maxTurns بيحدد كم دور الـ agent يقدر يشتغل. permissionMode بيضبط مستوى الصلاحيات. من الحقول المفيدة كمان: disallowedTools وskills لتحميل skills مختارة مسبقًا، وmcpServers لوصول MCP خاص بالـ agent، وinitialPrompt لإرسال أول دور تلقائيًا.
memory بيدي الـ agent تخزين دائم عبر الجلسات. أول 200 سطر من ملف MEMORY.md في مجلد الذاكرة بتاع الـ agent بتتحمّل في الـ system prompt تلقائيًا — Claude بيكتب في الملف ده لما يتعلم حاجات جديدة:
---
name: researcher
memory: user
description: Long-running research assistant with persistent notes
---
You are a research assistant. Check your MEMORY.md at session start to recall previous findings. Update it with new discoveries.isolation: worktree بيدي الـ agent git worktree خاص بيه وbranch منفصل يعمل فيه تغييرات من غير ما يلمس الـ working tree الأساسي. لما يخلّص، بيرجّع مسار الـ worktree واسم الـ branch عشان تراجعه وتعمل merge. لو ما عملش أي تغييرات، الـ worktree بيتمسح تلقائيًا. وطول ما الـ agent شغّال، Claude بيعمل lock للـ worktree عشان عملية التنظيف ما تشيلهوش، وبيفك الـ lock لما الـ agent يخلّص. الـ worktree بيتفرّع من الـ default branch بتاع الـ repo (origin/HEAD) إلا لو ظبطت worktree.baseRef على head في الـ settings، وساعتها الـ agents المعزولة بتبدأ من الـ HEAD المحلي وبتشيل معاها الشغل اللي لسه ما اتـpushتش.
background: true بيخلّي الـ agent يشتغل دايمًا كـ background task، عشان المحادثة الأساسية تفضل حرة. اضغط Ctrl+B عشان تحوّل agent شغّال حاليًا للخلفية.
فيه CLI flags بتوسّع اللي الجلسة تقدر توصله. --add-dir <path> بيدّي صلاحيات Read/Edit لمجلدات إضافية غير مجلد العمل الأساسي — مفيد لما الكود بتاعك بيشير لـ shared libraries أو packages في مجلدات مجاورة في monorepo. الـ skills في .claude/skills/ في المجلدات المضافة بتتحمّل تلقائيًا. اضبطها بشكل دائم بـ permissions.additionalDirectories في الإعدادات. --mcp-config <path> بيحمّل تعريفات MCP servers من ملف JSON واحد أو أكتر للجلسة الحالية بس، وبيتدمج مع مصادر الـ MCP بتاعت المستخدم/المشروع. ضيف --strict-mcp-config عشان تتجاهل مصادر المستخدم/المشروع وتستخدم بس الملفات اللي حددتها:
claude --add-dir ~/projects/shared-types --add-dir ~/projects/design-tokens
claude --mcp-config ./ci-servers.jsonعشان تفرض موديل واحد على كل subagent وteammate وworkflow agent — متجاهلًا أي override للـ model سواء وقت الـ spawn أو في تعريف الـ agent — اضبط CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (Claude Code v2.1.257 أو أحدث). الموديل المختار بييجي من CLAUDE_CODE_SUBAGENT_MODEL أو، لو مش متضبط، من موديل الجلسة الأساسية:
# ثبّت كل الـ subagents على Sonnet لـ refactor حساس
CLAUDE_CODE_SUBAGENT_MODEL=sonnet CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 claudeاستخدام وتسلسل الـ Subagents
Claude بيشغّل الـ agents تلقائيًا لما وصف المهمة يطابق الـ description field بتاع الـ agent. عبارات زي “use proactively” ممكن تشجّع التفويض، بس الاستدعاء الصريح هو الطريقة المضمونة لما تحتاج agent معين. استخدم صيغة @"agent-name (agent)" عشان تضمن استخدام agent بعينه، وتتخطى المطابقة التلقائية.
الاستدعاء الصريح بلغة طبيعية كمان بيشتغل:
Use the security-reviewer agent to audit the new auth module.
Have the test-engineer agent write integration tests for the payment service.
Ask the debugger agent to investigate the memory leak in src/workers/queue.ts.الـ agents ممكن يتسلسلوا ورا بعض، بحيث output واحد يغذّي اللي بعده. شغّل claude agents من الـ terminal عشان تفتح واجهة الـ Agent — قائمة بكل جلسات Claude Code بتوضّح حالتها (working, waiting, completed, failed, idle, stopped) وآخر نشاط. ده مفيد لمتابعة agents كتير شغّالين بالتوازي. مرّر --cwd <path> عشان تفلتر الـ roster على الجلسات اللي اتفتحت تحت المسار ده — مفيد لما تكون شغّال على أكتر من repo وعايز تشوف بس الجلسات بتاعت المشروع الحالي. اضبط CLAUDE_CODE_DISABLE_AGENT_VIEW=1 عشان تعطّلها. كمان تقدر تشغّل session كاملة مع agent معين بـ claude --agent <name>، وتقيّد الـ agents اللي coordinator يقدر يشغّلها بـ Agent(...) tool allowlists.
# اعرض بس جلسات الـ agents اللي بدأت تحت ~/work/api
claude agents --cwd ~/work/apiللسكربتات اللي محتاجة تستهلك الـ roster — boot scripts على شكل tmux-resurrect، أو status bars مخصصة، أو session pickers — مرّر --json لـ claude agents عشان تاخد نفس البيانات كـ array بصيغة قابلة للقراءة آليًا بدل العرض التفاعلي. كل عنصر بيتضمن pid وcwd وkind وstartedAt، وكمان sessionId وname وstatus لما يكونوا متضبطين. لما status يبقى waiting، الحقل waitingFor بيقولك الجلسة مستنية إيه بالظبط — زي permission prompt أو input needed — فالسكربت يقدر يوجّه كل حالة لإجراء مختلف:
# صحّي بس الجلسات اللي مستنية إذن صلاحية
claude agents --json \
| jq -r '.[] | select(.status == "waiting" and .waitingFor == "permission prompt") | .sessionId' \
| xargs -I {} claude respawn {}First use the code-analyzer agent to find performance bottlenecks, then use the optimizer agent to fix them.كمان تقدر تبدأ جلسة منفصلة عن الـ terminal من الأول: claude --bg "investigate the flaky test" (وكمان --background) بيشغّلها كـ background agent وبيرجّعلك التحكم فورًا، وبيطبع الـ session ID والأوامر اللي بتديرها. اجمع --bg مع --exec عشان تشغّل shell command كـ background job بدل جلسة Claude، أو مع --agent عشان تحط subagent معيّن في الخلفية — ومينفعش تتجمّع مع -p/--print. بعد ما الجلسة تبقى في الخلفية، أدِرها من الـ shell من غير ما تفتح واجهة الـ Agent الكاملة: claude attach <id> بيجيبها للـ terminal الحالي، claude logs <id> بيطبع آخر output ليها، claude stop <id> (وكمان claude kill) بيوقّفها، claude respawn <id> بيعيد تشغيل جلسة شغّالة أو متوقفة بمحادثتها كاملة (مرّر --all عشان تعيد تشغيل كل الجلسات الشغّالة، مثلًا عشان تلتقط نسخة Claude Code محدّثة)، وclaude rm <id> بيشيلها من الـ roster مع الاحتفاظ بالـ transcript على جهازك عشان claude --resume يقدر يفتحها تاني.
Claude Code جاي معاه عدة agents جاهزة مش محتاج تعملها: general-purpose للمهام العامة متعددة الخطوات، Explore بيورث موديل جلسة الـ main (capped at opus) للتحليل السريع للكود (قراءة فقط)، Plan بيبحث في الكود قبل ما يقدّم خطط تنفيذ، وclaude-code-guide بيجاوب على أسئلة عن مميزات Claude Code. خلّ بالك: Explore وPlan بيتخطوا ملفات CLAUDE.md والـ git status بتاعك عشان البحث يفضل سريع وغير مكلف — كل الـ built-in agents التانية والـ custom subagents بتحمّل الاتنين. Claude كمان يقدر يكمّل محادثة سابقة لـ agent بدل ما يبدأ من الأول — إرسال متابعة بـ SendMessage({to: agentId}) بيعمل resume للـ agent ده بكامل الـ context بتاعه، بينما استدعاء Agent جديد بيبدأ محادثة جديدة دايمًا.
افتراضيًا، الـ subagent يقدر يعمل spawn لـ subagents خاصة بيه، لحد ثلاث طبقات تحت المحادثة الرئيسية — بدءًا من v2.1.219 الافتراضي بقى ثلاثة (كان واحد في v2.1.217–v2.1.218). التداخل ده مناسب لمهمة مفوَّضة بتنقسم هي نفسها لمهام فرعية متوازية — زي reviewer subagent بيوزّع verifier لكل ملاحظة — بحيث الـ output الوسيط ما يوصلش للمحادثة الرئيسية وبس ملخّص الـ subagent الأعلى هو اللي بيرجعلك. عند حد العمق، Claude Code بيحجب أداة Agent عن كل subagent ما عدا الـ fork، فالـ subagent اللي وصل للحد بيعمل شغله المفوَّض بنفسه. اضبط CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (v2.1.217+) على عدد الطبقات اللي عايزها تحت المحادثة الرئيسية، أو 1 عشان توقف التداخل. غير عمق التداخل، في حد للتزامن (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS، الافتراضي 20 شغّالين في نفس الوقت، v2.1.217+ — جلسات ultracode مستثناة) بيحدّد كام subagent يشتغلوا في نفس الوقت. وما بقاش في إجمالي لكل جلسة: حد الـ 200 spawn لكل جلسة (CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION، اتضاف في v2.1.212) اتشال في v2.1.224، فالجلسات اللي بتستمر طويلًا ما بترفضش agents جديدة بسبب إجمالي spawn على مستوى الجلسة.
لما تشغّل الـ subagents بشكل غير تفاعلي بـ -p، تقدر تحقن تعليمات مشتركة في الـ system prompt بتاع كل subagent — بما فيهم الـ nested subagents، ما عدا الـ forked subagent اللي بيعيد استخدام prompt المحادثة نفسها. --append-subagent-system-prompt "Cite file paths in every answer" (v2.1.205+) بيضيف النص لـ system prompt كل subagent؛ وللتعليمات الطويلة اللي مينفعش تتكتب في سطر الأوامر، --append-subagent-system-prompt-file ./subagent-rules.txt (v2.1.261+) بيحمّل نفس النص من ملف. الاتنين مينفعش يتجمّعوا، والاتنين بيشتغلوا بس في وضع -p. (لـ prompt الـ main agent نفسه، البدائل هي --append-system-prompt و--append-system-prompt-file.)
افتراضيًا المحادثة بتسجّل الـ system prompt بتاعها في أول request وبتعيد استخدام النسخة المسجّلة دي في الـ requests اللي بعدها. وإنت بتظبط صياغة --append-system-prompt أو --append-subagent-system-prompt عبر تشغيلات --continue، إعادة الاستخدام دي معناها إن تعديلاتك بتتجاهل — مرّر --system-prompt-snapshot off (v2.1.257+) عشان يعيد بناء الـ prompt في كل request بدل كده. قبل v2.1.268، التسجيل ده كان بيشتغل بس في الجلسات اللي بتجيب feature flags، زي حسابات claude.ai وConsole افتراضيًا؛ والجلسات اللي مبتجيبش الـ flags دي — بما فيها Bedrock وGoogle’s Cloud Agent Platform وFoundry — كانت بتعيد بناء الـ prompt في كل request برضه، والـ flag مكانش ليه تأثير.
الـ subagent forking مفعّل افتراضيًا في الجلسات التفاعلية بدءًا من v2.1.232 — وبيفضل متعطّل افتراضيًا في وضع -p غير التفاعلي والـ Agent SDK. الـ forked subagent بيورث الـ conversation context الكامل من الجلسة الرئيسية بدل ما يبدأ من الصفر، فتقدر تسلّمه مهمة جانبية من غير ما تشرحله الموقف من الأول، والـ forked spawns بتشتغل في الخلفية. شغّله بـ /subtask (v2.1.212+). استخدم متغيّر البيئة CLAUDE_CODE_FORK_SUBAGENT عشان تغيّر السلوك الافتراضي: 1 بيفعّل الـ forking كمان في الوضع غير التفاعلي والـ Agent SDK، و0 بيعطّله في كل أنواع الجلسات:
CLAUDE_CODE_FORK_SUBAGENT=0 claude # عطّل الـ forking في كل مكانخاصية Agent Teams التجريبية (محتاجة CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) بتنسّق بين عدة Claude instances بيشتغلوا بالتوازي عبر قائمة مهام وصندوق رسائل مشترك. الـ flag --teammate-mode بيتحكم في طريقة العرض (in-process مقابل split-pane)؛ مش بيفعّل الميزة لوحده. ده للمشاريع الكبيرة متعددة الملفات اللي agents مستقلين يقدروا يشتغلوا على أجزاء مختلفة في نفس الوقت من غير ما يتداخلوا. SendMessage بيعمل resume تلقائي للـ agents المتوقفين لما ترسل لهم رسالة، فمش محتاج تعمل resume يدوي قبل ما تتواصل معاهم. بدءًا من v2.1.178، أداتا TeamCreate وTeamDelete اتشالت: مع تفعيل متغيّر البيئة، كل جلسة عندها بالفعل team ضمني واحد، فبتعمل spawn للزملاء مباشرة عن طريق parameter الـ name في أداة Agent — من غير خطوة setup — والتنظيف بيتم تلقائيًا لما الجلسة تخلص.
الرسائل بين الجلسات (Cross-Session Messaging)
أدوات SendMessage وListAgents (v2.1.224+) بتشتغل كمان بين جلسات Claude Code المستقلة — يعني الجلسات اللي أنت بتبدأها وبتوجّهها بنفسك، مش subagents ولا زملاء الفريق. الجلسة المستقبِلة بتقرأ الرسالة بين استدعاءات الأدوات خلال turn نشط، فأداة شغّالة ما بتتقاطعش أبدًا؛ لو الجلسة idle، turn جديد بيبدأ بالرسالة. الميزة شغّالة من غير ما تفعّل حاجة على macOS وLinux، بتشتغل على نفس الجهاز out of the box، وبتوصل جلساتك على أجهزة تانية وClaude Code on the web لما جلسة الإرسال تكون متّصلة بـ Remote Control.
استخدم cross-session messaging لما واحدة من جلساتك عندها حاجة جلسة تانية محتاجاها في نص الشغل: تغيير breaking اكتشفته جلسة بيأثر على شغل جلسة تانية، إجابة سؤال حلّته جلسة وكانت جلسة تانية مستنّياه، تحديث حالة من migration طويلة، أو handover بين جلسات شغّالة على نفس الـ repository في worktrees منفصلة. لمشاركة محادثات كاملة أو context بين terminals، استخدم /resume — لأن الرسالة نص عادي، مش history.
كل جلسة بتقرّر تعمل إيه بالرسالة الواردة، والافتراضي بيعتمد على permission modes للجانبين: الرسائل للجلسة اللي بتطلب permissions بتتوصّل، بينما الرسائل للجلسة اللي شغّالة بـ bypassed permissions بتتجمّد لحد ما توافق، إلا لو المُرسِل كمان bypass. غيّر الافتراضي عن طريق إعداد crossSessionInbound — accept بيوصّل تلقائي، hold بيحطّ الرسالة في الانتظار لحد ما توافق، refuse بيرمي. الـ dialog بتاع الرسالة المجمّدة بيخلص بعد dialogExpiry (الافتراضي خمس دقايق)؛ اضبطها على "never" عشان تحتفظ بالرسائل المجمّدة الافتراضية لحد ما الجلسة تخلص. من إعدادات المشروع أو المحلية، refuse بيطبّق فوق أي مصدر تاني؛ من إعداداتك كـ user، بيطبّق إلا لو managed settings أو --settings حدّدوا قيمة. عشان تقفل الميزة بالكامل، ضيف SendMessage وListAgents لقائمة permissions.deny — رفض SendMessage كمان بيقفل الرسائل للـ subagents وزملاء الفريق لأن نفس الأداة بتخدم التلاتة:
{
"permissions": {
"deny": ["SendMessage", "ListAgents"]
},
"crossSessionInbound": "refuse"
}مش محتاج تنادي الأدوات بنفسك: Claude بيكتشف الهدف بـ ListAgents وبيبعت بـ SendMessage لما يلاقي حاجة، أو لما تطلبه منه. عشان تسمّي الهدف بنفسك، اكتب @ وبعدها أول حروف اسم الجلسة واختارها من الـ typeahead (v2.1.232+)، زي ما بتمنشن subagent بـ @. الجلسات بتتـ address باسمها اللي بتحدده بـ /rename أو --name؛ من غير اسم، Claude Code بيستنتج اسم من اسم مجلد العمل.
cross-session messaging بتشتغل على macOS وLinux، محتاجة Claude Code v2.1.224 أو أحدث، ومعتمدة على الـ provider وإعدادات الجلسات الاتنين. للمؤسسات، الـ administrators يقدروا يجمعوا قواعد الـ deny مع crossSessionInbound: "refuse" في managed settings عشان يقفلوا الاتجاهين.