الوحدة 10 — السب-agents، والوكلاء المتوازون، وفرق agents

محادثة مع Claude Code قويّة ما دامت تتّسع في سياق مقروء. يتعذّر ذلك بعد حجم معيّن — تدقيق خمسة وعشرين ملفًّا، أو هجرة ثلاثمائة مكوّن —، فيغرق الخيط الرئيس وتُستنزَف ميزانيّة الرموز. الحلّ ليس «prompt أقوى»، بل التفويض. يعرض Claude Code أربع عائلات متكاملة: سب-agents، وforks، وفرق agents، وسير عمل ديناميكيّ.

لماذا نُفوِّض ومتى

قاعدة للحفظ: كلّ سب-agent جديد هو سياق جديد. لا يرى تاريخك، ولا /clear عندك، ولا الملفّات المقروءة سابقًا. يستقبل prompt النظام، ورسالة مهمّة، وملفّات CLAUDE.md الموروثة.

الفائدة دقيقة: هذا العزل يعزل الضوضاء أيضًا. pytest -x -vv يُنتج ألفَي سطر من traces، وبحث Grep على ثلاثمائة ملفّ، وقراءة سجلّات Kubernetes: كلّها تبقى داخل السب-agent، ولا يصعد سوى الملخّص. المقابل هو زمن الإقلاع: السب-agent يبدأ باردًا.

المنهج	ما تحصل عليه	متى تستخدمه
سب-agents	عمّال مفوَّضون في جلسة واحدة، بسياق معزول، يُرجعون ملخّصًا	مهمّة قد تُغرق الخيط الرئيس (سجلّات، بحث، خرج اختبارات)
عرض «agent view»	شاشة تُوزّع وتراقب جلسات تعمل في الخلفيّة (claude agents)	عدّة مهامّ مستقلّة تُطلقها وتراقبها
فرق agents	جلسات منسَّقة، قائمة مهامّ مشتركة، مراسلات بين وكلاء. تجريبيّ، معطَّل افتراضيًّا	Claude يُقطّع مشروعًا ويُوزّع القطع ويُزامن العمّال
سير عمل ديناميكيّ	سكربت Claude يُنسِّق كثيرًا من السب-agents ويُقاطع نتائجهم	تدقيق مستودع كامل، هجرة مئات الملفّات، بحث بمصادر متقاطعة

ثلاث أدوات تدعم من دون أن تكون في ذاتها طرق تشغيل للـagents: worktrees (كلّ جلسة في checkout git مستقلّ، فلا نزاع تحرير)، والمراسلات بين الجلسات لتناقل الاكتشافات، والأمر /batch الذي يجمع السب-agents والـworktrees في حركة واحدة.

السب-agents: اللبنات الأساسيّة

السب-agent المخصّص ملفّ Markdown مع رأس YAML في .claude/agents/ (مشروع، تحت الإدارة الإصداريّة) أو ~/.claude/agents/ (مستخدم). يُراقب Claude Code هذين المجلّدَين ويُعيد التحميل خلال ثوانٍ؛ يلزم إعادة تشغيل عند الإنشاء الأوّل في نطاق ما. name وdescription وحدهما إلزاميّان.

الحقول الموثَّقة في الـfrontmatter:

الحقل	الدور
name	مُعرِّف فريد بأحرف صغيرة وشُرَط؛ : ممنوع (محجوز للـplugins)
description	متى يجب على Claude التفويض
tools / disallowedTools	قائمة سماح / قائمة رفض للأدوات (تُطبَّق قائمة الرفض أوّلًا)
model	sonnet أو opus أو haiku أو fable أو ID كامل أو inherit
permissionMode	default أو acceptEdits أو auto أو dontAsk أو bypassPermissions أو plan
maxTurns	حدّ الأدوار قبل التوقّف؛ يوسم الخرج بأنّه جزئيّ
skills / mcpServers / hooks	موارد مقيَّدة بهذا السب-agent
memory	user أو project أو local (ذاكرة دائمة)
background	true للبقاء في الخلفيّة
isolation	worktree لـcheckout git مستقلّ
color / initialPrompt	العرض، الرسالة الأولى المُرسَلة تلقائيًّا مع --agent

ثلاث طرق للاستدعاء. لغة طبيعيّة: «استخدم السب-agent revieweur». @-mention: @"revieweur (agent)" يفرض النداء. جلسة كاملة: claude --agent revieweur يستبدل prompt النظام طوال الجلسة.

يمكن إعادة استدعاء سب-agent أنتج خرجًا: يستدعي Claude SendMessage بالمعرِّف أو الاسم. تعيش الـtranscripts في ~/.claude/projects/{project}/{sessionId}/subagents/agent-{id}.jsonl وتبقى بعد /compact.

سب-agents مدمجون

ثلاثة سب-agents مدمجون موجودون بلا تصريح: Explore (استكشاف الشيفرة، قراءة فقط)، وPlan (إعداد خطّة قبل التحرير)، وgeneral-purpose (مهامّ دون تعريف دقيق). Explore وPlan one-shot: بلا ID، وغير قابلَين للاستئناف.

حدود التوازي والعمق

يحكم متغيّران التخمين. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS يُحدّد عدد السب-agents المتزامنين في الجلسة — 20 افتراضيًّا؛ يرفض ما فوق ذلك عبر أداة Agent بالرسالة Concurrent subagent limit reached. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH يتحكّم بالتعشيش: 3 افتراضيًّا. عند العمق الأقصى، تُسحب أداة Agent من السب-agent. ضبطه على 1 يُعطّل التعشيش.

{
  "env": {
    "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS": "8",
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Forks: المحادثة كاملةً، بالتوازي

الـfork سب-agent خاصّ: يرث prompt النظام والأدوات والنموذج وكامل تاريخ المحادثة الرئيسة. بلا إعادة تهيئة. يُستخدَم لتجربة نسخة بديلة من دون تلويث الخيط: كتابة اختبارات أثناء البرمجة، أو تجربة مقاربتَين من نقطة واحدة.

الأمر المخصّص هو /subtask (Claude Code v2.1.212+، /fork قبل ذلك):

/subtask اكتب اختبارات وحدة للـparser مع التغييرات الأخيرة

يعمل الـfork في الخلفيّة، ونتيجته تصل رسالةً. لا يستطيع توليد fork آخر، وذاكرته المُخبَّأة مشتركة مع المحادثة الرئيسة — وهذا ما يجعله رخيصًا. وضع fork نشط افتراضيًّا في الجلسة التفاعليّة؛ يُضبَط عبر CLAUDE_CODE_FORK_SUBAGENT.

أوامر أساسيّة

• /tasks — عرض العمل الجاري في الخلفيّة: سب-agents نشطون ومنجَزون، وأوامر shell. زرّ Entrée يفتح الـtranscript، وx يوقف أو ينظّف.
• /list-agents (أو /peers) — قائمة السب-agents وزملاء الفريق وجلسات Claude Code القابلة للانضمام، مع الاسم الدقيق للمراسلة بين الجلسات.
• /agents — انتبه للفخّ. منذ v2.1.198 لم يعد هذا الأمر يفتح محرِّرًا: يذكِّر فقط بمكان التحرير (.claude/agents/ أو ~/.claude/agents/).
• /batch <instruction> — skill مقدَّمة تدرس المستودع، وتُقسّم المهمّة إلى 5 حتّى 30 وحدة مستقلّة، وتعرض خطّة، ثمّ تُطلق سب-agent لكلّ وحدة، كلّ منها في worktree خاصّ، وكلّ منها يفتح PR. مثاليّة لهجرة ضخمة.
• /workflows — متابعة سير العمل الديناميكيّ: إيقاف مؤقّت، واستئناف، وحفظ.

Worktrees: العزل على مستوى الملفّات

الـworktree مجلّد git منفصل، متفرّع من المستودع الرئيس، بملفّاته الخاصّة. جلستان في worktreeَين لا يتزاحمان أبدًا:

claude --worktree feature-paiement

يُنشأ الـworktree تحت .claude/worktrees/feature-paiement/ على فرع worktree-feature-paiement. عند الخروج، يسأل Claude Code ماذا يفعل إن بقيت تغييرات. ولإعطاء سب-agent checkout خاصًّا به، يكفي إضافة isolation: worktree إلى الـfrontmatter: يُنشئ Claude Code worktree مؤقّتًا وينظّفه إن لم يبقَ تغيير.

ملفّ .worktreeinclude (بصياغة .gitignore) ينسخ تلقائيًّا ملفّات مُتجاهَلة (عادةً .env) إلى كلّ worktree جديد.

فرق agents (تجريبيّ)

تُنسِّق فرق agents عدّة جلسات Claude Code بقيادة lead. تجريبيّ، معطَّل افتراضيًّا: يُفعَّل عبر CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 في env. بعد التفعيل، يكفي وصف المهمّة: «شغّل ثلاثة زملاء لاستكشاف المسألة من ثلاث زوايا». يفتح الـlead قائمة مهامّ مشتركة، ويولّد الزملاء، ويوزّع العمل.

نمطان للعرض: in-process (نفس الطرفيّة، تنقّل بالأسهم وEntrée) وsplit panes (كلّ زميل في pane تحت tmux أو iTerm2). الضبط عبر teammateMode في settings.json أو --teammate-mode. تنبيه: الزملاء ليسوا معزولين في worktrees، فيتعيّن تقسيم الملفّات.

سير العمل الديناميكيّ

سير العمل الديناميكيّ سكربت يكتبه Claude يُطلق كثيرًا من السب-agents ويقاطع نتائجهم. يلائم الحال حين لا تكفي حفنة سب-agents: تدقيق مستودع كامل، وهجرة 500 ملفّ، وبحث بمصادر متقاطعة. توجد سير عمل مقدَّمة (/deep-research) متاحة مباشرةً؛ ويمكن أيضًا طلب كتابة سيرٍ عمل من Claude، والموافقة عليه في plan mode، ثمّ حفظه لإعادة التشغيل. المتابعة عبر /workflows.

Kiosque: سب-agentان كاملان

في Kiosque، تُبرمج نادية سب-agentَين على مستوى المشروع، تحت الإدارة الإصداريّة في .claude/agents/. الأوّل يُراجع الشيفرة، والثاني ينفّذ مجموعة الاختبارات في سياق معزول.

السب-agent 1 — revieweur

الهدف: إجراء مراجعة ما بعد التعديل بالقراءة فقط ورفع ملخّص مُرتَّب. لا حقّ في التحرير، ولا وصول إلى Write.

---
name: revieweur
description: يُجري مراجعة شيفرة على تغييرات Python الأخيرة. استخدم بشكل استباقيّ بعد جلسة برمجة.
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: plan
color: blue
---

أنت مراجع Python أقدم لقاعدة شيفرة Kiosque.

عند استدعائك:
1. شغّل `git diff main...HEAD` لتحديد التغييرات.
2. ركّز على ملفّات `.py` المعدَّلة.
3. طبّق قائمة التحقّق التالية وارفع ملخّصًا.

قائمة التحقّق:
- القابليّة للقراءة، والتسمية، وغياب الشيفرة المُكرَّرة.
- معالجة أخطاء صريحة (لا `except:` عار).
- لا سرّ ظاهر، ولا مفتاح API مودَع في git.
- التحقّق من المدخلات في جانب FastAPI.
- تغطية اختبارات كافية للسلوك المعدَّل.
- migrations من Alembic مُولَّدة إذا تغيّر المخطّط.

قدّم في ثلاث فِقَر:
- «حاجب»: يجب إصلاحه قبل الدمج.
- «للمراجعة»: تحسينات مُوصى بها.
- «تفاصيل»: أمور أسلوب أو ذوق.

لا تُعدّل أيّ ملفّ.

السب-agent 2 — testeur

الهدف: تنفيذ make test في worktree معزول (كي لا يُلوَّث الـcheckout الرئيس إن أنشأ اختبار ملفًّا مؤقّتًا)، ورفع الفشل وحده.

---
name: testeur
description: ينفّذ مجموعة اختبارات Kiosque في worktree معزول ويرفع فقط حالات الفشل مع traces.
tools: Read, Bash, Grep
model: haiku
isolation: worktree
maxTurns: 10
color: green
hooks:
  PostToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "${CLAUDE_PROJECT_DIR}/.claude/hooks/annotate-tests.sh"
---

أنت مُنفِّذ اختبارات لـKiosque.

عند استدعائك:
1. تحقّق أنّك فعلًا داخل worktree (`git rev-parse --show-toplevel`).
2. شغّل `make test` بإخراج كامل.
3. إن نجحت كلّها: أعِد «مجموعة خضراء: N اختبار، T ثانية».
4. إن فشل اختبار: استخرج لكلّ إخفاق اسم الاختبار، والملفّ، والسطر، وأوّل سطر assertion، وخمسة أسطر سياق من الـtrace.
5. لا تُعِد تشغيل المجموعة على اختبار مفرد دون طلب.
6. لا تُعدّل أيّ شيفرة مصدر أو أيّ migration.

صيغة الخرج عند الفشل:
- عدد الاختبارات المنفَّذة، وعدد الفاشلة.
- قائمة الإخفاقات (الاسم، والمسار، ومقتطف trace).
- بلا أيّ تعليق «سبب محتمل»: الوقائع فقط.

الاستعمال اليوميّ

يكتب كريم @"revieweur (agent)" راجع services/paiement/`` قبل فتح PR: يقرأ الـrevieweur ولا يمسّ شيئًا، ويرفع ثلاث قوائم مُرتَّبة. تُطلق ليا @"testeur (agent)" شغّل المجموعة كاملةً بينما تواصل البرمجة: يعمل الـtesteur في worktree مؤقّت، ولا يصعد سوى الفشل. لعمل أوسع — نقل جميع الـendpoints إلى Pydantic v2 —، تُطلق نادية /batch اهجُر endpoints من services/ إلى Pydantic v2: تقسيم إلى 20 وحدة، سب-agent لكلّ وحدة في worktree، وPR لكلّ وحدة.

متى نُفضِّل فريق agents

revieweur + testeur = سب-agentان. يصبح الفريق مفيدًا حين يحتاج عدّة بشر افتراضيّين إلى محادثة بينهم (معماريّ، backend، frontend، يتفاعل كلٌّ منهم مع رسائل الآخرين). للعمل الفرديّ القابل للتفويض بلا تفاصيل، ابقَ على السب-agents.

الخلاصة

• السب-agents: سياق معزول، وخرج ملخّص، وYAML في .claude/agents/. الحقول الأساسيّة: name، description، tools، model، permissionMode، isolation، maxTurns، skills، hooks.
• Forks (/subtask): سب-agent يرث كامل السياق؛ توازٍ رخيص.
• الحدود: CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (20) وCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (3).
• الأوامر: /tasks و/list-agents و/subtask و/fork و/batch و/workflows؛ ولم يعد /agents يفتح محرِّرًا.
• Worktrees: --worktree <nom> يعزل جلسةً؛ isolation: worktree على سب-agent يمنحه checkout خاصًّا.
• فرق agents (تجريبيّ): CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. سير العمل الديناميكيّ: سكربتات Claude بمقياس واسع، متابعة عبر /workflows.

الوحدة التالية: MCP: ربط Claude Code بأدواتك وبياناتك — كيف نفتح Claude Code على GitHub، وقاعدة Postgres، ونظام تتبّع تذاكر، دون كتابة شيفرة الاندماج بأنفسنا.