تتعامل معظم الفرق مع Claude Code كأنّه وكيل واحد. هذه نصف القيمة فقط.

التحرّر الحقيقي هو الـ sub-agents — شخصيّات متخصّصة لها system prompts خاصة بها، وأدوات مسموح بها، وقواعد. أنت لا تتحدّث إلى "Claude". تتحدّث إلى code-reviewer، ثم إلى test-writer، ثم إلى migration-runner. كلّ واحد يلتزم مساره ويُتقن مهمّة واحدة.

إليك الـ 11 sub-agents الذين أشغّلهم على كلّ قاعدة كود جدّية، مهامّهم، وتعريفات .claude/agents/<اسم>.md التي تجعلهم يعملون.

لماذا sub-agents أصلاً؟

الوكيل الأحادي عامّ. العامّ رائع حين تكون المشكلة صغيرة. على قاعدة كود حقيقيّة تريد:

• مراجِعًا يُراجع فقط ولا يكتب الكود أبدًا.
• كاتب اختبارات لا يُعدّل أبدًا كود التطبيق.
• مُشغّل ترحيلات يُشغّل الترحيلات فقط ثم يتوقّف.

القيد هو الميزة. كلّ sub-agent مُقيّد بـ system prompt وقائمة أدوات مسموح بها. هذا التقييد هو ما يجعلهم موثوقين.

الـ 11 الذين أحتفظ بهم في كلّ مشروع

1. code-reviewer

المهمّة: مراجعة ما بعد التنفيذ. يقرأ الـ diffs ولا يكتبها أبدًا.

# system
أنت تراجع diffs. لا تعدّل الملفات. تُخرج:
1. أخطاء (مع ملف:سطر)
2. مناطق مخاطرة (أمن، أداء، تغييرات كاسرة)
3. مخالفات الأسلوب/الاتفاقيات مقابل CLAUDE.md
4. حكم في سطر واحد: SHIP أو FIX-FIRST أو REWRITE.

# tools
allow: ["git diff *", "rg *", "cat *"]
deny:  ["edit", "shell-write"]

2. test-writer

يكتب اختبارات جديدة. لا يُعدّل أبدًا كود الإنتاج. إن فشل الاختبار، يُبلّغ بالفشل — لا "يُصلحه".

3. test-fixer

الصورة المرآة. يقرأ الاختبارات الفاشلة، ويُعدّل كود الإنتاج لتنجح، ولا يعدّل الاختبار إلّا إذا كان مُثبَتًا أنّه خطأ.

4. migration-runner

يُشغّل ترحيلات قواعد البيانات. مسموح: pnpm db:migrate، psql -c "...". مرفوض: كلّ أوامر shell الأخرى.

5. dependency-auditor

pnpm outdated، pnpm audit، npm-check-updates. يُخرج جدول markdown للترقيات + المخاطر. لا يُشغّل ترقيات بلا إشراف.

6. release-bot

يولّد changelogs، bumps الإصدارات، الـ tags. لا يدفع أبدًا — الـ push للبشر فقط.

7. docs-writer

يلمس README.md وdocs/ وتعليقات JSDoc. ممنوع من src/ وapp/.

8. refactor-surgeon

إعادة هيكلة نقيّة. القيد: صفر تغيير سلوك، يجب أن تنجح كلّ الاختبارات قبل وبعد. إن فشل اختبار، فالـ refactor لم يكن نقيًّا — تراجع.

9. incident-responder

من تستدعيه فقط أثناء انقطاع الخدمة. يقرأ logs، يكتب هيكل postmortem، يقترح أوامر rollback. لا يُشغّل أبدًا أوامر إنتاج.

10. architect

read-only. ينظر إلى قاعدة الكود، يُنتج مسودّة ADR (سجلّ قرار معماري) عند سؤال "هل ينبغي أن نضيف X؟"

11. ci-fixer

يقرأ .github/workflows/، logs CI الفاشلة، ويقترح تغييرات دنيا. مسموح له بدفع فروع، أبدًا إلى main.

ما يدخل في .claude/agents/<اسم>.md

كلّ وكيل ملفّ واحد. هذا الشكل القياسي:

---
name: code-reviewer
model: claude-sonnet-4
---

# system
<شخصيّة + نطاق + صيغة الإخراج>

# tools
allow: [...]
deny: [...]

# احترام CLAUDE.md
اقرأ CLAUDE.md للمشروع قبل التصرّف.

هذا كلّ شيء. commit هذا المجلّد، ويحصل الفريق على نفس الطاقم.

كيف يتعاونون (دون أن يُسمّى ذلك "متعدّد الوكلاء")

هذا ليس بعد خطوط أنابيب متعدّدة الوكلاء (هذا في المقال 7). هذا الكوريغرافيا الأبسط:

أنت → /agents → اختر test-writer → "اكتب اختبارات لـ lib/cache.ts"
  → /agents → اختر test-fixer    → "اجعلها تنجح"
  → /agents → اختر code-reviewer → "راجع الـ diff"
  → /release-notes

كلّ خطوة محدودة. كلّ خطوة قابلة للمراجعة. لن تجد أبدًا وكيلاً واحدًا "كتب الاختبارات، أصلح الكود، راجع نفسه، ودفع إلى main". هذه المراجعة الذاتيّة هي بالضبط نمط الفشل الذي تريد تصميمه خارج النظام.

قاعدة التسمية

تُسمّى الـ sub-agents وفق الأدوار، لا الأدوات. code-reviewer لا claude-with-rg. migration-runner لا psql-runner. الأدوار تتركّب؛ الأدوات لا.

عندما ينضمّ زميل جديد، يقرأ .claude/agents/ مرّة واحدة فيفهم النموذج التشغيلي فورًا. هذه توثيق بالتكوين.

مثال حيّ: شحن ميزة بالطاقم

أنت: /agents test-writer
> اكتب حالات vitest لـ lib/cache.ts تغطّي انتهاء TTL وإخلاء LRU.
test-writer: <يكتب اختبارين، كلاهما يفشل، يُبلّغ>

أنت: /agents test-fixer
> اجعل تلك الاختبارات تنجح دون تغيير lib/cache.test.ts.
test-fixer: <ينفّذ TTL + LRU في lib/cache.ts، الاختبارات خضراء>

أنت: /agents code-reviewer
> راجع الـ diff.
code-reviewer: SHIP.

أنت: /release-notes
release-bot: <يكتب changelog>

أنت: git checkout -b feat/cache-lru && git commit && gh pr create

كتبت ~20 سطرًا بلغة طبيعيّة. ثلاثة متخصّصين مختلفين كتبوا / تحقّقوا / صادقوا على الكود الفعلي. هذا هو سير العمل.

ابنِ خاصّتك

ابدأ باثنين: code-reviewer و test-writer. استعملهما في كلّ PR لأسبوع. ستكتشف أين الاحتكاك وتُضيف الثالث عضويًا — عادةً ci-fixer أو migration-runner.

بحلول الشهر الثاني، كلّ فريق onboarded عندي يمتلك 6 إلى 8 sub-agents مُلتزمين في .claude/agents/، ويُعاملون كبنية تحتيّة.

---

المقال التالي: سلامة قاعدة الكود في الإنتاج — الصلاحيات، الحواجز، وأمور لا يجب أن يلمسها أيّ sub-agent دون إشراف.