وكلاء Claude Code الفرعيون بـ .claude/agents

يقوم الوكيل الفرعي بعمل واحد في نافذة خاصة به ويعود بملخص. استخدم واحدًا عندما قد يدفن البحث أو تشغيل الاختبار أو المراجعة ملف بملف المحادثة التي لا تزال تحتاجها. تكتب هذه المختبرات خمسة وكلاء يمكنك الالتزام بهم. أوامر الجلسة والأعلام موجودة في Claude Code cheat sheet.

ما هو الوكيل الفرعي

كل وكيل فرعي مخصص هو ملف Markdown. يعيّن الجزء الأمامي الاسم الذي يفوّض Claude إليه، والأدوات التي قد يستدعيها، والموديل الذي يعمل عليه. الجسم يستبدل رسالة النظام العادية لـ Claude Code لهذا الوكيل. لا يزال يستقبل تفاصيل البيئة الأساسية مثل دليل العمل.

تشاهد الجلسة الأب صف أداة قصيرة واسم الوكيل والنتيجة النهائية. القراءات الوسيطة تبقى في نسخ الوكيل الفرعي ضمن ملفات جلسة المشروع في ~/.claude. هذا الانقسام هو السبب في إنشاء وكيل ستعاود الطلب عليه كل يوم بخلاف ذلك.

الوكلاء المدمجة موجودة بالفعل. Explore يبحث في الشجرة بدون تحرير. Plan يجمع السياق بينما الجلسة الأساسية في وضع الخطة. لا تحتاج لإعادة تعريفهم. وكيل مشروع أو مستخدم اسمه Explore يتجاوز الواحد المدمج.

الوكلاء الفرعيون هي شكل واحد من أعمال agentive: موديل، وقائمة أدوات، وشرط إيقاف. ليسوا خوادم MCP. MCP يعرّض أدوات خارجية. وكيل فرعي هو جلسة Claude أخرى برسالة نظام أضيق.

تنسيق الملف

فقط name و description مطلوبان. المفاتيح غير المعروفة تُتجاهل. name بحد أقصى 256 حرفًا ولا يمكن أن يحتوي على :، لأن أسماء النقطتين محجوزة للمكونات الإضافية. اسم الملف لا يجب أن يطابق name، لكن مطابقته تحافظ على المجلد قابلاً للقراءة.

حقول أخرى مدعومة ستستخدمها فعلاً:

isolation: worktree فروع من الفرع الافتراضي للريبو، وليس من HEAD الحالي الخاص بك. يُزال worktree عندما لا يُجري الوكيل تغييرات. اتركه بدون عندما يجب أن يرى الوكيل الفرع الذي تحقق منه.

cd داخل الوكيل لا يعلق بين استدعاءات الصدفة، ولا يغير دليل الجلسة الأساسية.

حيث يعيش الملف

يتم اكتشاف وكلاء المشروع بالمشي لأعلى من دليل العمل إلى جذر الريبو. إذا عرّف مجلدان من تلك المجلدات name نفسه، فالواحد الأقرب إلى دليل العمل يفوز. Claude Code يمسح أيضًا المجلدات الفرعية، لذلك .claude/agents/review/security.md تخطيط صالح. التزم بوكلاء المشروع. احتفظ بالتجارب الشخصية في ~/.claude/agents/.

Claude Code يراقب ~/.claude/agents/ ودليل المشروع .claude/agents/. التعديلات تظهر خلال بضع ثوان. ثلاث حالات لا تزال تحتاج إعادة تشغيل: دليل agents أُنشئ بعد بدء الجلسة، الملف موجود في دليل أضفته مع --add-dir، أو الجلسة بدأت مع --disable-slash-commands.

/agents في الإصدارات الحالية يطبع تذكيرًا لتحرير هذه الملفات. في Claude Code v2.1.197 وأقدم فتح واجهة مدير. الوكلاء في الخلفية الذي يعمل بالفعل مدرجة مع /tasks، التي تشمل cheat sheet.

تحقق من الجزء الأمامي مع claude plugin validate .claude/agents. يحتاج هذا التحقق Claude Code v2.1.233 أو أحدث. يُبلغ عن الملفات التي لا تُحلل. لا يشكو من name مفقود إذا كان YAML نفسه يُحلل.

عندما يفوّض Claude

Claude يقارن طلبك، وصف الوكيل description، والسياق الحالي. وصف يقول متى يعمل أكثر فائدة من وصف يقول فقط ما هو الوكيل. تشير الوثائق إلى العبارة “use proactively” كطريقة لتشجيع التفويض. احتفظ بالأوصاف قصيرة. إذا تجاوزت الأوصاف المجمعة من وكلائك المخصصين 15,000 رمز، Claude Code ينذر عند البدء ولا يزال يحمل كل وكيل. انقل التعليمات الطويلة إلى الجسم، الذي يحمل فقط عندما يعمل هذا الوكيل.

التفويض خيار. وصف غامض يخسر أمام Explore أو أمام الجلسة الأساسية تفعل العمل بنفسها.

للاستدعاء الصريح ثلاث مستويات:

تبدو بنية mention التي تظهر الوكلاء في typeahead مثل هذا:

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

يمكنك أيضًا كتابة @agent-code-reviewer بدون picker. بينما تكتب ذلك الشكل، القائمة تظهر الملفات. mention لا يزال يحل عندما ترسله. جملتك تذهب إلى الأب. الأب يكتب طلب المهمة الذي يستقبله الوكيل الفرعي فعلاً.

وكيل المكون الإضافي يظهر كاسم مجال، على سبيل المثال @agent-my-plugin:code-reviewer. إذا جلس ملف المكون الإضافي في مجلد فرعي، المجال يشمل هذا المجلد: my-plugin:review:security.

--agent يستمر عندما تستأنف الجلسة. إذا كان ملف الوكيل ذهب في وقت الاستئناف، الجلسة تستمر مع الأدوات الافتراضية وتظهر تحذيرًا.

وكلاء مرة واحدة يمكن تمريرهم كـ JSON. هذا الشكل للإطلاق واحد، وليس لملف تلتزم به:

claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'

في وضع الطباعة على v2.1.281 أو أحدث، --agents قد يشير إلى ملف JSON. جلسة تفاعلية ترفض مسار ملف هناك.

خمسة وكلاء

أسماء الأدوات أدناه هي تلك التي يستخدمها مرجع الوكيل الفرعي: Read، Grep، Glob، Edit، Write، و Bash. إدراج الأدوات هو ما يبقي مراجع من التحرير. حقل tools المحذوف يرث المجموعة الفرعية الكاملة.

مراجع الكود

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews local diffs for correctness bugs and missing tests. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a code reviewer for this repository.

Run git status and git diff. Read only the files that diff touches, plus tests next to them.
Report findings as blocking, should-fix, or note.
Each finding needs a file path and the failure mode.
Skip style nits that a formatter would fix.
Do not edit files and do not commit.

Bash على هذا الوكيل لذلك يمكنه تشغيل git diff. يمكنه أيضًا تشغيل أوامر صدفة أخرى، لذلك الرسالة يجب أن تحرّم التحريرات والالتزامات. إذا احتجت لإيقاف صعب، اترك Bash وقبِل أن الأب يجب أن يلصق الفرق في رسالة التفويض.

كاتب الاختبارات

.claude/agents/test-writer.md

---
name: test-writer
description: Adds or updates tests for code that just changed. Use when the user asks for tests or a change has no coverage.
tools: Read, Grep, Glob, Edit, Write, Bash
model: sonnet
---

You write tests that match this repo's existing runner and layout.

Read the changed code and one nearby test file before you add anything.
Cover the behavior that regressed or that the change claims to add.
Do not change production code except to expose a test hook the project already uses.
Run the narrowest test command that executes the new test.
If it fails, fix the test. If production code is wrong, stop and report that instead of rewriting it.

مدقق الأمان

.claude/agents/security-auditor.md

---
name: security-auditor
description: Read-only pass over auth, secrets, and risky shell or SQL. Use proactively before a security-sensitive change merges.
tools: Read, Grep, Glob
model: sonnet
---

You audit this repository for security issues a reviewer can verify from the code.

Look for secrets in the tree, auth checks that trust the client, command injection, and queries built with string concatenation.
Cite the file and the pattern. Say how it could be hit.
Do not modify files. Do not run exploits. Do not request credentials.
If you are unsure, label the item as needs-human and quote the line.

لا Bash وبدون أدوات الكتابة. الوكيل لا يمكن “just curl production” لفحص فكرة.

كاتب الوثائق

.claude/agents/doc-writer.md

---
name: doc-writer
description: Updates README or docs so they match the code. Use when behavior changed and the docs were not part of the edit.
tools: Read, Grep, Glob, Edit, Write
model: haiku
---

You update documentation to match the code.

Read the implementation first. Edit the existing doc page that already describes the feature.
Describe behavior a caller can observe. Do not invent flags or paths.
If the code is ambiguous, write the question at the top of your summary and skip the doc edit.

model: haiku يبقي تمرير الكلمات على الاسم الأصغر. الأب يمكن أن يبقى على Sonnet. انظر قسم التكلفة أدناه.

مصحح الأخطاء

.claude/agents/debugger.md

---
name: debugger
description: Finds why a failing test or command fails. Use when the user pastes a stack trace or says a check is red.
tools: Read, Grep, Glob, Bash, Edit, Write
model: inherit
maxTurns: 12
---

You debug one failure.

Reproduce it with the command in the task before you edit.
Change the smallest surface that explains the failure.
Re-run that command. If it still fails, report what you tried and stop.
Do not clean up unrelated files.

model: inherit يتابع موديل الجلسة. maxTurns: 12 يوقف مصحح أخطاء يحلقة. النتيجة تعود بعلامة جزئية، ويمكنك طلب Claude استئناف ذلك الوكيل بنفسه بدلاً من بدء واحد جديد.

مثالب

الوكيل لا يرى محادثتك. وكيل فرعي غير-fork يبدأ نظيفًا. لا يحصل على سجلك، أو مهارات استدعيتها بالفعل، أو ملفات الجلسة الأب قرأتها بالفعل. يحصل على رسالة نظامه الخاصة، رسالة التفويض، CLAUDE.md من المستويات التي حملتها الأب (إلا إذا تُعيّن omitClaudeMd)، لقطة git status عندما تكون في ريبو git، وأي مهارات سميّت في skills. Explore و Plan تتخطى تحميل CLAUDE.md ولقطة git.

ضع الحقائق التي يجب ألا يفتقدها الوكيل في الجملة التي ترسل، أو في جسم Markdown الخاص به. “استخدم debugger على الفشل الذي ناقشناه” تفويض ضعيف. “استخدم debugger على npm test -- auth.test.ts. التأكيد هو expected 401.” تفويض كامل.

fork، التي يمكنك البدء بـ /subtask، يرث المحادثة الأب بدلاً من ذلك. هذا الأداة عندما إعادة وضع الخلفية قد تكلف أكثر من تقاسمها. Forks هي ميزة مختلفة من الملفات الخمسة أعلاه.

تدفع للموديل الثاني. طلبات الوكيل الفرعي تُحتسب ضمن حدود الاستخدام ذاتها مثل الجلسة الأساسية. أوصاف كل وكيل مخصص يحمل أيضًا في الأب، حتى تحذير 15,000 رمز. مراجع haiku أرخص من وراثة Opus لتمرير كلمات. نافذة سياق الوكيل الفرعي هي نافذة موديله الخاص، لذلك موديل أصغر نافذة أصغر أيضًا.

هناك حد تزامن. مرة واحدة 20 وكيلاً يعملون، spawn آخر من أداة Agent يفشل مع خطأ concurrent-limit حتى ينهي واحد. ذلك الحد يحتاج Claude Code v2.1.217 أو أحدث، والجلسات مع ultracode على معفاة. رفعه هو CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. نادرًا تريد حد أعلى على محمول.

Worktrees ليست فرعك. isolation: worktree يبدأ من الفرع الافتراضي. وكيل مطلوب مراجعة عمل غير ملتزم على فرع ميزة لن يرى ذلك العمل إذا فعّلت isolation.

الاستئناف صريح. كل تفويض يبدأ مثالاً جديدًا. عندما ينهي الوكيل، الأب يستقبل معرّف وكيل ويمكنه استئنافه، يحتفظ بنسخة الوكيل الفرعي. Explore و Plan لا تعود معرّف. اطلب من الأب متابعة code-reviewer، أو ابدأ واحدًا جديدًا إذا كان المرور الأول كافيًا.

الخطافات داخل الوكيل ليست خطافات جلسة. الجزء الأمامي hooks يعمل بينما يعمل هذا الوكيل. خطاف Stop مكتوب هناك يطلق كـ SubagentStop. خطافات المشروع في settings.json أيضًا تعمل للأدوات التي يستدعيها الوكيل، مع agent_id و agent_type على المدخل. guides يظهر ملف الإعدادات. وكلاء المكون الإضافي تتجاهل hooks، mcpServers، و permissionMode في الجزء الأمامي الخاص بهم.

قائمة تحقق متكررة يجب أن تبقى في المحادثة الأساسية هي slash command، وليس وكيل. وكيل للوسط الضجاج من مهمة.

الأسئلة الشائعة

ما هو وكيل Claude Code الفرعي؟

وكيل فرعي هو مساعد منفصل مع نافذة سياق خاصة به، ورسالة نظام، وقائمة أدوات، وموديل. Claude يفوض مهمة جانبية إليه ويعيد ملخصًا، لذلك تبقى تفريغات البحث وملفات السجل خارج المحادثة الرئيسية. كل استدعاء وكيل فرعي هو طلب موديل خاص به ويُحتسب ضمن حدود الاستخدام ذاتها مثل المحادثة الأساسية.

كيف أضيف وكيلاً فرعيًا مخصصًا؟

أنشئ ملف Markdown في .claude/agents/ لريبو واحد، أو في ~/.claude/agents/ لكل المشاريع على جهازك. الجزء الأمامي يحتاج إلى name و description. tools و model اختياريان. جسم Markdown هو رسالة النظام. إذا لم يكن دليل agents موجودًا عند بدء الجلسة، أعد تشغيل Claude Code مرة واحدة حتى يتم التقاط المجلد الجديد.

كيف أجبر Claude على استخدام وكيل فرعي واحد؟

اكتب @ واختر الوكيل من typeahead، أو اكتب @agent-code-reviewer في الطلب. تلك الإشارة تضمن تشغيل الوكيل للمهمة. تسميته في جملة، مثل “استخدم وكيل code-reviewer الفرعي”، يطلب Claude التفويض ولا يزال يترك الخيار مفتوحًا. claude --agent code-reviewer يجعل هذا الوكيل الجلسة كاملة.

لماذا تجاهل وكيلي الفرعي المحادثة؟

وكيل فرعي عادي يبدأ من سياق نظيف. لا يرى سجل المحادثة الخاص بك، أو المهارات التي استدعيتها بالفعل، أو الملفات التي قرأتها الجلسة الأب. Claude يكتب رسالة تفويض، والوكيل يعمل من ذلك بالإضافة إلى رسالة نظامه الخاصة وملفات CLAUDE.md التي يُسمح له بتحميلها. fork هو الاستثناء: يرث المحادثة الأب.

هل تكلفة الوكلاء الفرعيين إضافية؟

يرسلون طلباتهم الخاصة على الموديل الذي عينته، وتلك الطلبات تُحتسب ضمن حدود الخطة ذاتها أو استخدام API مثل الجلسة الأساسية. مراجع haiku ينفق أقل من واحد opus. حقول الوصف من وكلائك المخصصين تجلس أيضًا في السياق الأب، وينذرك Claude Code عند البدء عندما تتجاوز تلك الأوصاف معًا 15,000 رمز.