Slash Command المتقدم: الوكلاء الفرعيون وتنسيق الأدوات

غطّت المقالتان الأوليتان ماهية slash command (ملف Markdown) وكيفية استخدام البادئة ! لحقن مخرجات الـ shell في السياق. هذه المقالة تذهب أبعد: كيف تجعل أمرًا واحدًا ينسّق أقوى قدرات Claude Code — مراجع الملفات، الوكلاء الفرعيون، أدوات MCP — مع إبقاء الصلاحيات تحت السيطرة.

عند الوصول إلى هذه الطبقة، لم يعد الـ command مجرد "اختصار لِـ prompt"، بل صار سير عمل صغيرًا قابلًا لإعادة الاستخدام.

---

مرجع @file: حقن ساكن أنسب من !cat

يستطيع !cat file.md أن يحشر محتوى الملف داخل السياق، لكنه يمر عبر الـ shell وله عدة مساوئ: كل تشغيل يستدعي إنشاء عملية فرعية؛ وحين يحتوي مسار الملف على مسافات أو محارف خاصة يجب escape إضافي؛ كما أن Claude Code لا يتعرّف عليه بوصفه "ملفًا"، بل مجرد قطعة نص.

أما مرجع @ فهو native:

---
description: مراجعة التغييرات وفق معايير المشروع
---

راجع المعايير التالية:

@.claude/context/coding-standards.md
@.claude/context/security-checklist.md

الآن راجع التغييرات في git diff، وأشر إلى كل مخالفة للمعايير.

!`git diff HEAD`

يخبر @path الـ Claude Code أن "يُلحق هذا الملف بالمحادثة كمرفق". الفروقات:

السيناريو	استخدم !cat	استخدم @
المسار يأتي من وسيط ($ARGUMENTS)	✅ الوحيد الممكن هو !cat	❌ @ لا يدعم توسيع المتغيرات
معايير وقوالب المشروع الثابتة	⚠️ ممكن لكنه ثقيل	✅ native ويوفر استدعاء shell
محتوى ديناميكي (diff، log، نتائج اختبار)	✅ ! إلزامي	❌ لا يصلح

القاعدة: للملفات الثابتة استخدم @، وللمخرجات الديناميكية استخدم !، وللمسارات المعلمَة استخدم !cat $ARGUMENTS.

---

allowed-tools: وضع حدود صلاحية للـ command

افتراضيًا، عند تنفيذ الـ command يستطيع النموذج استخدام كل الأدوات الموجودة في الجلسة. أحيانًا لا يكون هذا ما تريده — فمثلًا /review مهمّة مراجعة للقراءة فقط، ولا ترغب أن "يلمس بالمصادفة" سطرًا واحدًا من الكود.

أضف allowed-tools في الـ frontmatter، فخلال فعالية الأمر لن يُسمح إلا بالأدوات المذكورة:

---
description: مراجعة كود للقراءة فقط
allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
---

راجع الفرق بين الفرع الحالي وماستر قراءةً فقط، دون أي تعديل.

!`git diff master...HEAD`

بعض النقاط المهمة:

• Bash(git diff:*) تفويض دقيق — يسمح فقط باستدعاءات bash التي تبدأ بـ git diff، أما git push فسيُحظَر
• Read / Grep / Glob يمنح بوضوح أدوات القراءة فقط
• لم تُذكر Edit / Write، فلن يتمكّن النموذج من استدعائها حتى لو أراد تعديل الكود

بالمثل، يمكن تفويض أمر عالي الصلاحية مثل /deploy بالاتجاه المعاكس:

---
description: نشر الفرع الحالي
allowed-tools: Bash(kamal deploy:*), Bash(git push:*), Read
---

تحديد "ما يستطيع هذا الأمر فعله" سلفًا أوثق بكثير من الاعتماد على مراجعة بشرية لكل prompt عند كل تشغيل.

---

استدعاء الوكلاء الفرعيين: عزل المهام الملتهمة للسياق

بعض المهام تُفجّر سياق المحادثة الرئيسية — تصفّح عشرات الملفات للعثور على كل نقاط استدعاء دالة، تشغيل إحصاءات للـ codebase، سحب مقطع log كبير للتحليل. إذا نُفّذت مباشرة داخل المحادثة الرئيسية، ستبقى آلاف الأسطر من المخرجات في السياق، وستصبح الحوارات اللاحقة أبطأ وأقل ذكاءً.

الطريقة الصحيحة أن تُسلّم هذه الأعمال إلى subagent: يعمل الوكيل الفرعي في سياق مستقل، وبعد الانتهاء يعيد الخلاصة فقط إلى المحادثة الرئيسية. يكفي أن تُوجّه ذلك صراحةً داخل الـ command:

---
description: تحقيق معمّق في كل استخدامات رمز
allowed-tools: Task
---

استخدم subagent من نوع Explore للتحقيق معمّقًا في كل استخدامات الرمز التالي: $ARGUMENTS

اطلب من الـ subagent أن يغطي:
- كل مواقع الاستدعاء (بما فيها ملفات الاختبار)
- السيناريوهات التجارية المشمولة
- هل توجد تطبيقات بديلة مكافئة

بعد عودة الـ subagent، أعطني فقط ملخصًا لا يتجاوز 300 كلمة، ولا تُلصق مقاطع كود خام.

عند تشغيل /trace SomeClass#some_method سيُنشئ Claude Code وكيلًا فرعيًا من نوع Explore يمسح الـ codebase بالتوازي، بينما لا تستقبل المحادثة الرئيسية سوى الخلاصة المقطّرة. لا مخرجات grep، ولا مقاطع ملفات، والسياق يبقى نظيفًا.

مستوى متقدّم:

---
description: تحقيق متوازٍ في ثلاثة خيارات مرشّحة
allowed-tools: Task
---

أطلق 3 subagents في الوقت نفسه، كل واحد يبحث في أحد مسارات التطبيق الثلاثة التالية:

1. استخدام ActiveJob + Sidekiq القائمَيْن
2. استخدام Solid Queue
3. بناء queue خفيف يدويًا

يُجيب كل وكيل عن: حجم العمل، المخاطر، درجة التدخّل في الكود القائم. بعد وصول الخلاصات الثلاث، سأتكفّل أنا بالمقارنة.

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

---

استدعاء أدوات MCP: جعل الـ command يطال أنظمة خارجية

إذا ربطت الجلسة بخوادم MCP (Linear، GitHub، Sentry، بروكسي قاعدة بيانات داخلي وغيرها)، يستطيع الـ command أن يُوجّه النموذج لاستدعاء هذه الأدوات مباشرةً:

---
description: توليد قائمة مهام تنفيذ من Linear issue
allowed-tools: mcp__linear__*, Read, Grep
---

اقرأ الوصف الكامل وتعليقات Linear issue $ARGUMENTS.

بالجمع مع الحالة الراهنة للـ codebase (ابحث بنفسك عن الملفات ذات الصلة باستخدام Grep/Read)، ضع قائمة بمهام التنفيذ:
- ما الملفات التي يجب تعديلها
- هل يُقدَّم كل خطوة كـ commit مستقل أم مجموعة دفعة واحدة
- هل ثمة نقاط غامضة تحتاج إلى توضيح مسبق مع الـ PM

لا تبدأ كتابة الكود، قدّم الخطة فقط.

يمنح mcp__linear__* صلاحيات كل أدوات Linear MCP، فيصبح بوسع النموذج سحب تفاصيل الـ issue، تعليقاته، وحالته. ويصبح الـ command برمّته نقطة انطلاق سير عمل "من التذكرة إلى خطة التنفيذ".

النقطة الجوهرية: عند كتابة اسم أداة MCP داخل allowed-tools يجب استخدام بادئتها الكاملة (mcp__<server>__<tool>)، وإلا فلن يسري التفويض.

---

فخ تركيب الأوامر: الـ slash لا يتوسّع بشكل تعاودي

سوء فهم شائع جدًا: أن تكتب /test داخل ملف /review ظنًّا منك أنه سيُشغّل أمر الاختبار. لن يفعل. فالـ slash command لا يُوسَّع إلا مرة واحدة على مستوى الإدخال الأعلى من المستخدم؛ وأي /xxx داخل الـ command هو مجرّد نص عادي — يقرؤه النموذج، لكن Claude Code لن يذهب لتنفيذه.

إذا أردت تركيب عدة أوامر، فهناك عدّة طرق صحيحة:

الطريقة أ: اسحب المنطق المشترك إلى ملف context، ويستخدمه كل أمر عبر @ أو !cat

@.claude/context/review-checklist.md
@.claude/context/security-checklist.md

الطريقة ب: اكتب داخل الـ command صراحةً "تصرّف مثل /review" + كرّر التوجيهات الجوهرية

ليست أنيقة لكنها فعّالة. فما دامت التوجيهات واضحة بما يكفي، سيسلك النموذج الطريق ذاته.

الطريقة ج: يستخدم أحد الأوامر أداة Task لإطلاق subagent، ويعيد prompt الـ subagent استعمال نفس ملفات السياق

كل تنسيق حقيقي لسير العمل يمر من هذا الطريق. يتولّى الـ command الأب المهام التنسيقية والتلخيص، ويتولى الـ subagent تنفيذ الخطوات الفعلية.

النمط المضادّ الذي يجب تجنّبه: كتابة الـ command على مئات الأسطر في محاولة لإنهاء كل شيء بأمر واحد. فحين تنفجر حبيبية التنفيذ ترتفع كلفة الصيانة بشدّة، ويبتلع أمر واحد ميزانية التوكنات لجولة كاملة.

---

متى تستخدم الثلاثية

وصلنا الآن إلى نقطة توفّرت فيها أساسًا آليات حقن "القدرات الخارجية" في أوامر Claude Code. كيف تختار:

الحاجة	الآلية المفضّلة
معايير وقوالب ووثائق سياق ثابتة	مرجع @file
حالات آنية (diff، log، نتائج اختبار، استعلام قاعدة بيانات)	حقن !shell
محتوى ملفات معلمَن	!cat $ARGUMENTS
بحث ملتهم للسياق، وبحث عابر للملفات	subagent عبر Task
أنظمة خارجية (issue tracker، مراقبة، بيانات production)	أدوات MCP + allowed-tools
سير عمل متعدد الخطوات متسلسل/متوازٍ	أمر أب ينسّق subagents

تُعلَن حدود الصلاحية صراحةً عبر allowed-tools، خصوصًا للأوامر المشتركة داخل الفريق — فتثبيت ما يستطيع الأمر فعله أوثق من الاعتماد على موافقة يدوية في كل مرة.

---

مثال قريب من الإنتاج

بعد تجميع كل ذلك، إليك أمر "التحقيق في مسار التنفيذ اعتمادًا على Linear ticket":

---
description: إنتاج خطة تنفيذ اعتمادًا على Linear ticket
allowed-tools: mcp__linear__*, Task, Read, Grep, Glob, Bash(git log:*)
---

## السياق

@.claude/context/architecture.md
@.claude/context/coding-standards.md

## الحالة الراهنة للـ codebase

!`git log --oneline -10`

## المهمة

اسحب وصف Linear ticket $ARGUMENTS، تعليقاته، والتذاكر المرتبطة.

ثم أطلق subagent اثنين على التوازي:
1. الأول: يبحث في الـ codebase عن جميع التطبيقات الحالية ذات الصلة، والوحدات القابلة لإعادة الاستخدام
2. الثاني: يقيّم المخاطر — ما مسارات الكود عالية الحركة التي سيمسّها هذا التغيير، وهل ثمة فجوات في تغطية الاختبارات

بعد عودة كلا الوكيلَيْن، أخرج:
- خطوات التنفيذ (مرتّبة بحسب التبعيات)
- قائمة المخاطر
- حبيبية الـ commit الموصى بها

لا تبدأ كتابة الكود.

عند تشغيل /plan ENG-4213، يتمّ كل شيء بتوجيه واحد: سحب التذكرة ← بحث متوازٍ في الـ codebase ← تقييم المخاطر ← تجميع الخطة. كل ما يبقى على المستخدم هو قراءة الخلاصة ثم اتخاذ قرار الانطلاق.

---

هذا هو القوس الكامل للمقالات الثلاث الأولى من سلسلة slash command: تعريف prompts قابلة لإعادة الاستخدام (intro) ← حقن السياق ديناميكيًا (context) ← تنسيق الأدوات والوكلاء الفرعيين (هذه المقالة). عند هذه الطبقة، لم يعد .claude/commands/ مجرّد اختصارات، بل مكتبة صغيرة لسير عمل الفريق.