توسيع Claude Code: CLAUDE.md وhooks وsubagents وMCP

في الفصول الخمسة الماضية ثبّتنا Claude Code وأعطيناه التعليمات وخرجنا من التعثّر وصمّمنا الأذونات. وهذا الفصل حديث عن إعادة تشكيل الأداة نفسها. والتوسعات لا تُستعمل بحفظ أسمائها. والنافع هو جدول يقابل بين «ما الذي يحلّ ضيقك الحالي» وبينها.

خريطة التمييز ― أربعة أسئلة تحسم الأمر

التوسعات ستّ، لكن ما تفكّر فيه أربعة فقط: أيكفي الرجاء / أتريد أثراً مؤكّداً / أتريد فصل السياق / أتريد الوصل بالخارج ― فإن سألت نفسك بهذا الترتيب تحدّد الجواب تحديداً شبه قاطع.

أيكفي الرجاء

إن كان الإخلال أحياناً غير قاتل فالكلام يكفي. والجواب CLAUDE.md (مقدّمات عامة) أو Skills (إجراءات عمل بعينه)

أتريد أثراً مؤكّداً

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

أتريد فصل السياق

إن كنت لا تريد أن تدفن مخرجات ضخمة مسارك الأصلي، فاجعله يعمل خارجاً ولا تتسلّم إلا الخلاصة. والجواب subagents

أتريد الوصل بالخارج

إن لزمتك معلومة لا سبيل للذكاء الاصطناعي إلى معرفتها (القيمة الحالية في قاعدة البيانات، أو محتوى نظام المهامّ). والجواب MCP

والسؤال الخامس «أستوزّع هذا على غيرك» ― فإن كنت ستوزّعه فـplugins. وأكثر ما يلتبس Q1 وQ2، أي CLAUDE.md وSkills وhooks. فكلها تبدو سواء، والفارق بينها متى تُقرأ ومن ينفّذها.

CLAUDE.md ― افصل التحميل عن الالتزام

يوفر CLAUDE.md سياق المشروع في كل جلسة إذا وُضع في موضع يُحمّل منه. استخدم ~/.claude/CLAUDE.md للتعليمات المشتركة بين المشاريع. محتواه تعليمات نصية، وليس إعدادات تفرض أذونات العمليات.

إذا قال الوكيل إنه قرأ الملف ثم لم يلتزم به، فافحص هذه الأسئلة الثلاثة بصورة منفصلة.

هل حُمّل؟ افحص CLAUDE.md والقواعد في قسم Memory files داخل /context. يؤثر موضع بدء الجلسة وإعدادات الاستبعاد في الملفات المشمولة. لا يظهر AGENTS.md المحمّل مباشرة في هذه القائمة، لذلك لا يثبت غيابه وحده أنه لم يُقرأ
هل عاد بعد الضغط؟ يُعاد تحميل CLAUDE.md في جذر المشروع من القرص وإدراجه بعد /compact. وتُعاد قراءة ملفات CLAUDE.md الفرعية والقواعد الخاصة بالمسارات عند قراءة ملفات مطابقة. أما القرارات المحفوظة في المحادثة وحدها فتُعامل بصورة مختلفة
هل أثّر في الفعل؟ حتى بعد تأكيد التحميل، افحص غموض القواعد وتعارض التعليمات بصورة منفصلة. لا تفترض أن أحدث تعليمة تفوز دائماً. حدّد النطاق وشروط الاستثناءات

التوجيه الرسمي هو أقل من 200 سطر لكل ملف CLAUDE.md. ليس هذا حداً للتحميل ولا فاصلاً يضمن الالتزام. احتفظ بالقواعد اللازمة كل مرة، وافصل التفاصيل مع شروط قراءتها. استيراد كل شيء عبر @path لا يقلل سياق البدء. استخدم Skills للإجراءات المطلوبة أحياناً، وقواعد المسارات للتعليمات المقصورة على ملفات معينة.

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

«قرأته» ليس دليلاً على الالتزام. افحص عرض التحميل بصورة منفصلة عن الفروق ونتائج الاختبارات. انقل الشروط القابلة للاختبار آلياً إلى hooks أو CI كما سنرى تالياً، واذكر النطاق الذي بقي من دون تحقق.

hooks ― فحوص تعمل عند تحقق الشروط

التعليمة النصية مثل «لا تعدّل ملف .env» لا تضمن نسبة معينة من الالتزام. إذا احتجت إلى فحص شرط ومنع عملية قبل التنفيذ، فانظر في إعدادات الأذونات والخطّافات.

نتناول هنا الخطّافات من نوع command التي تشغّل أوامر الصدفة. عندما تطابق الإعدادات المفعّلة الحدث والشروط، يشغّلها Claude Code نفسه. لا تحتاج إلى أن يتذكر النموذج تشغيلها، لكنها لا تعمل إذا عُطّلت في الإعدادات أو كان مسار التنفيذ خارج نطاقها. راجع ما hooks في Claude Code للاطلاع على الفكرة. فيما يلي تسعة أحداث تمثيلية، وليست قائمة كاملة.

SessionStart        عند البدء أو الاستئناف
UserPromptSubmit    عقب الإرسال مباشرةً                 [يمكن الحجب]
PreToolUse          قبيل الأداة = البوّاب                [يمكن الحجب]
PostToolUse         بعد نجاح الأداة = التنسيق            (لا يعيد العملية المكتملة إلى ما قبلها)
Notification        انتظار الإدخال أو انتظار الإذن
Stop                نهاية الردّ                          [يمكن الحجب]
SubagentStop        انتهاء الوكيل الفرعي                 [يمكن الحجب]
SessionEnd          انتهاء الجلسة
PreCompact          قبل الضغط                            [يمكن الحجب]

يختلف ما يمكن منعه باختلاف الحدث. منع أداة قبل التنفيذ يختلف عن منع انتهاء الرد حتى يستمر العمل. ارفض العمليات الخطرة عند PreToolUse ونسّق تلقائياً عند PostToolUse؛ وهما نقطتا بدء شائعتان. ضع الإعداد تحت المفتاح "hooks" في settings.json. ويحدّد موضع الملف النطاق (~/.claude/ للمستخدم، و.claude/ للمشاركة، وsettings.local.json للإعداد الشخصي).

لنحوّل الآن طلب «لا تعدّل ملف .env» الوارد في بداية هذا القسم إلى آلية. هذه صيغة مقصورة على .env من مثال «منع تعديل الملفات المحمية» في الدليل الرسمي. تحتاج إلى أمرين: الإعداد والسكربت.

① .claude/settings.json ― شغّل السكربت قبيل استدعاء Edit أو Write.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh"
          }
        ]
      }
    ]
  }
}

② .claude/hooks/protect-env.sh ― يمنع التعديل إذا بدأ اسم الملف المستهدف بـ.env (ومنها .env.local وما شابهه). على macOS وLinux امنح الملف صلاحية التنفيذ بالأمر chmod +x .claude/hooks/protect-env.sh.

#!/bin/bash
# .claude/hooks/protect-env.sh
command -v jq >/dev/null || { echo "لم يُعثر على jq، لذا أُوقف التعديل" >&2; exit 2; }

FILE_PATH=$(jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"   # حوّل فواصل مسارات Windows من \ إلى /

if [[ "${FILE_PATH##*/}" == .env* ]]; then
  echo "Blocked: $FILE_PATH ملف .env، فلن يُعدَّل" >&2
  exit 2
fi
exit 0

البنية هي اسم الحدث ثم مصفوفة من المطابقات والأوامر. يحدّد matcher اسم الأداة المستهدفة، و"Edit|Write" يطابق Edit أو Write (وحذفه يطابق جميع الأدوات). يتلقى الخطّاف JSON على الدخل القياسي، وفي Edit وWrite يحمل tool_input.file_path المسار المطلق للملف المستهدف. وعلى Windows يكون فاصل هذا المسار \، لذا يوحّده السكربت إلى / قبل المقارنة. عند المنع برمز الخروج 2، يصل نص الخطأ القياسي إلى Claude بوصفه سبب الرفض، فيقرؤه Claude ويبحث عن طريقة أخرى. أما 1 فيُعامل خطأً غير مانع وتستمر العملية، لذا استخدم 2 حين تريد المنع. و0 يعني عدم الاعتراض، فتنتقل العملية إلى فحص الأذونات المعتاد.

يستخدم السكربت bash وjq (ومثال الدليل الرسمي يفترض jq أيضاً). على Windows تعمل الخطّافات عبر Git Bash، وإن لم يوجد فعبر PowerShell؛ لذا يحتاج هذا المثال إلى Git Bash. ولكيلا تمر العملية دون فحص عند غياب jq، جعلنا أول خطوة في السكربت توقف التعديل.

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

طريقة الاختبار هي نفسها في الدليل الرسمي. اطلب من Claude «أضف سطر تعليق إلى .env»، فيتوقف قبل التعديل ويعود إلى Claude نص Blocked:. وجرّب معه أن الملفات غير .env ما زالت قابلة للتعديل كالمعتاد. وإذا أخطأت في كتابة مسار السكربت، فلن يظهر إلا إشعار Failed with non-blocking status code، بينما يبقى الباب مفتوحاً؛ فانتبه لهذا الإشعار أيضاً. ولاحظ أن هذا المثال لا يمنع إلا الأداتين Edit وWrite، أما التعديل بأوامر Bash أو PowerShell فمسار آخر؛ فوسّع النطاق بحسب ما تريد منعه. وتجد صيغ المخرجات والفروق بين الأحداث في دليل Hooks الرسمي.

ضع التكلفة في الحسبان مسبقاً: فالخطّافات من نوع command تشغّل أوامر الصدفة تلقائياً بصلاحيات حسابك، وتستطيع تعديل أي ملف يصل إليه حسابك أو حذفه. وتطلب الوثائق الرسمية أيضاً أن تقرأ كل أمر وتختبره قبل إضافته. أعدّ أوامر تثق بها فقط، وتحقق من المدخلات. والتعديلات التي تجريها مباشرة على ملفات الإعداد تسري تلقائياً في المعتاد. اعرض التسجيل عبر /hooks، وإذا لم يظهر أثر التعديل، فافحص JSON وموضع الملف قبل إعادة تشغيل الجلسة.

subagents ― تفويض بسياق منفصل

يمكن لمخرجات الاختبارات الكاملة والسجلات الضخمة أن تملأ السياق بنص كثير لم تكن تنوي إلا تصفحه سريعاً، فتزيح مقدمات مهمة. تشغّل الوكلاء الفرعية ذلك العمل في سياق منفصل وتعيد خلاصة النتيجة. ولها في المعتاد سياقها وتعليماتها وأذونات أدواتها، لذا يجب أن يمرر الوكيل الرئيسي المعلومات اللازمة صراحة. والاستثناء تنفيذ يتفرع من المحادثة ويرث سجل الوكيل الرئيسي؛ وهذا يختلف عن context: fork في المهارات. ولأن التقرير خلاصة، فاطلب تضمين الأدلة اللازمة والأسئلة التي لم تُحسم أيضاً.

يفيد الفصل ― في الاستقصاء الواسع، والتحقّق المصحوب بمخرجات كثيرة، والمهامّ المكتفية بذاتها التي يكفي منها الاستنتاج
يخسّرك الفصل ― في المعالجة المتتابعة، وكثرة الأخذ والردّ، والعمل المتوازي على الملفات نفسها، والإصلاح الذي ينتهي بخطوة أو خطوتين

وهي ميزة قياسية تُستعمل بلا إعداد. وإن أردت إضافة تعريف فاكتبه في .claude/agents/<الاسم>.md (أو ~/.claude/agents/ إن أردته مشتركاً)، وضع في مقدّمة YAML الحقول name وdescription وtools وmodel. وإدارتها بـ/agents، واستدعاؤها بـ@agent-<الاسم>. وابدأ بالوكلاء القياسيين: وكيل الاستكشاف ووكيل التخطيط والوكيل العام.

وdescription هو مفتاح الاستدعاء. فالوكيل الرئيس ينظر فيه ليحكم هل يفوّض إليه، فإن كان الوصف غامضاً قلّ احتمال اختياره تلقائياً. فحدّد فيه ماذا يفعل ومتى يُستعمل ― وهذا الفخّ نفسه موجود في Skills.

وأما Agent Teams الملتبس بها فآلية تتعاون فيها عدة جلسات مستقلّة عبر قائمة مهامّ مشتركة. وهي تجريبية باشتراك صريح ومعطّلة افتراضياً (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). ولأنها تشغّل نسخاً منفصلة فاستهلاك الرموز فيها كبير، ولا يمكن تعشيشها. والمقارنة في الفرق بين subagents وAgent Teams. وإن ترددت فالجلسة الواحدة أو subagents.

Skills ― تحويل الإجراءات إلى رصيد

في مقابل النمطيات من نوع «افعلها بهذه الخطوات كل مرة»، ميزة Skills أنها لا تُفتَح إلا عند الحاجة. وحقيقتها مجلد محوره ملف SKILL.md. تكتب في صدره name وdescription، وتحته الإجراءات بصيغة Markdown، ويمكنك أن تضمّ إليه reference/ وscripts/. ويكفي أن تضعه في .claude/skills/ (للمشروع) أو ~/.claude/skills/ (للمشترك) حتى يُتعرَّف عليه.

الجوهر هو الكشف المتدرّج. تدخل قائمة أسماء المهارات وأوصافها إلى السياق في المعتاد، بينما يُحمّل المتن بالاختيار التلقائي أو بالاستدعاء الصريح /skill-name. وتُقرأ المواد المساندة عند الحاجة. قائمة الأوصاف تستهلك السياق أيضاً؛ ومع كثرة المهارات قد تُختصر الأوصاف أو يُسقط بعضها لتناسب الميزانية. اكتب description محدداً، وتحقق بصورة منفصلة من استدعاء المهارة ومن أن إجراءها أنتج النتائج المطلوبة. وطريقة الكتابة في ما Claude Agent Skills.

في سطر واحد: CLAUDE.md مقدمات تُحمّل بصورة معتادة؛ وSkills إجراءات تُفتح بالاختيار التلقائي أو الاستدعاء الصريح؛ والخطّافات من نوع command معالجة تطلقها الأحداث والشروط المحددة في الإعدادات.

MCP ― مدّ اليد إلى أنظمة خارجية

MCP، أي Model Context Protocol، معيار لـالوصول إلى بيانات وعمليات خارجية، مثل القيم الحالية في قاعدة بيانات أو تذاكر تتبع المشكلات. فيما يلي طريقتان شائعتان للاتصال. شخّص السبب عبر الجمع بين طريقة الاتصال وتفاصيل الخطأ.

محلي عبر stdio — يبدأ الخادم كعملية فرعية على جهازك. ومفاتيح التشخيص هي مسار الملف التنفيذي ومتغيرات البيئة المطلوبة ومخرجات أخطاء الخادم
بعيد عبر HTTP — تتصل بالخادم عبر رابط. ومفاتيح التشخيص هي الرابط والشبكة وأخطاء الخادم وبيانات الاعتماد

ابدأ بالحالة والتفاصيل في /mcp. قد تظهر failed مع الخوادم المحلية والبعيدة. إذا احتوى Issue: في claude mcp get <name> على رمز HTTP أو نص خطأ، فاقرأه أيضًا. تشير needs authentication إلى فحص المصادقة، وتشير pending approval إلى الموافقة على خادم المشروع. إذا رُفضت ترويسة Authorization ثابتة برمز 401/403 أثناء الاتصال، تظهر failed رغم أن المشكلة في المصادقة. جُمعت الحلول في أخطاء اتصال MCP في Claude Code: الأسباب والحلول.

ضع ملف الإعدادات المشترك .mcp.json في جذر المشروع. استخدم env الخاص بكل خادم للمتغيرات المرسلة إلى stdio؛ ولمصادقة HTTP استخدم OAuth أو headers بحسب الخدمة. لا تكتب المفاتيح الفعلية مباشرة في الملفات المشتركة، بل أشر إلى متغير بيئة مثل ${API_KEY}. تتحول بعض أسماء المتغيرات، ومنها بيانات اعتماد Claude Code نفسه، إلى نصوص فارغة في الروابط والترويسات البعيدة؛ راجع أيضًا قواعد توسيع المتغيرات الرسمية.

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

plugins ― تحزيم المجموعة وتوزيعها

تتيح Plugins جمع المهارات وتعريفات الوكلاء الفرعيين والخطافات وإعدادات MCP لتوزيعها. إذا وفرت ملف تعريف لإضافة منفردة، فضعه في .claude-plugin/plugin.json. في البنية القياسية، توضع skills/ وagents/ وhooks/hooks.json و.mcp.json في جذر الإضافة نفسها. لا تضعها داخل .claude-plugin/. ويمكن الاستغناء عن ملف التعريف إذا استُخدمت البنية القياسية وحدها.

/plugin marketplace add owner/repo   ← تسجيل الكتالوج
/plugin install name@marketplace     ← تثبيت إضافات منفردة منه
/plugin list                         ← عرض الإضافات المثبتة عبر الأسواق

هذه هي الخطوات الأساسية للتثبيت عبر marketplace. تسجيل الكتالوج وحده لا يثبت الإضافات. يعرض /plugin list الإضافات المثبتة بهذا المسار، وليس كل الإضافات المتاحة عبر مجلدات المهارات أو المزامنة. النطاقات هي user لجميع مشاريعك، وproject للإعدادات المشتركة، وlocal لك وحدك في هذا المشروع. حتى في نطاق project، يحتاج كل عضو إلى تثبيت الإضافات من المصادر الخارجية. يدير المسؤول نطاق managed وتكون تغييرات المستخدمين على الإعدادات مقيدة. شرح الإنشاء متاح في إضافات Claude Code وMarketplace: الاستخدام والإنشاء والنشر.

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

بأيّها تبدأ ― حديث الترتيب

عرضنا ستّاً، لكن لا يلزمك إدخالها كلها. فإدخالها قبل وجود مشكلة لا يزيدك إلا تعقيداً في الإعداد. والترتيب من العرَض.

تشرح الشرح نفسه كل مرة ← CLAUDE.md. وإن كان لعمل بعينه فـSkills
كتبتها ولا يُلتزَم بها ← افحص التحميل والنطاق والتعارضات. انقل الشروط القابلة للاختبار آلياً إلى hooks
يمتلئ السياق سريعاً ← انقل الاستقصاءات الثقيلة إلى subagents، وعطّل ما لا يلزم من MCP
لا يصل الذكاء الاصطناعي إلى المعلومة ← MCP. صِل واحداً واحداً، ولا تنتقل إلى التالي حتى ترى الأول يعمل
تريد توزيع الإعداد نفسه ← plugins. وأحزم ما استقام لك استعماله وحده
لا يضايقك شيء ← لا تُدخل شيئاً. وهذه خير حال

والسطر الأخير ليس مزاحاً. فـالتوسعات تزيد أسباب التعثّر أيضاً ― وكثيراً ما تكون حقيقة «Claude Code يتصرّف بغرابة» طبقةً أضفتها أنت. ولهذا يأتي تشخيص الفصل الرابع أولاً.

الخلاصة

معيار الاختيار أربعة أسئلة: أيكفي الرجاء (CLAUDE.md وSkills) / أتريد أثراً مؤكّداً (hooks) / أتريد فصل السياق (subagents) / أتريد الوصل بالخارج (MCP). وللتوزيع plugins
CLAUDE.md يحمل تعليمات دائمة. يُعاد إدراج الملف الجذري بعد الضغط. اختصاره لا يضمن الالتزام؛ افحص التحميل والسلوك بصورة منفصلة
الخطّافات من نوع command يشغّلها Claude Code عند مطابقة الشروط المحددة. تحقق من مسارات التنفيذ وسلوك المنع؛ فالخطّاف اللاحق للعملية لا يتراجع عن فعل اكتمل
subagents تعمل في سياق منفصل ولا تعيد إلا خلاصة. ولا تناسب المعالجة المتتابعة ولا كثرة الأخذ والردّ
تستخدم Skills الكشف المتدرّج لفتح المتن عند الحاجة. اكتب أوصافاً دقيقة للاختيار التلقائي، وتحقق من نتائج الإجراء حتى بعد استدعائه صراحة
MCP معيار للوصول الخارجي. شخّص السبب بجمع الحالة في /mcp مع طريقة الاتصال وتفاصيل الخطأ
plugins صندوق التوزيع. وشيفرة غيرك تجري بصلاحياتك، فتحقّق من الناشر
وترتيب الإدخال من العرَض. واحداً واحداً بعد أن تولد المشكلة

أمّا المقارنة بين الأدوات نفسها والاختيار بينها ففي الفصل السادس «وسّع القدرات بالإضافات» من دورة البرمجة بالذكاء الاصطناعي.

وكلما توسّعت زاد الاستهلاك. ونتناول أخيراً التشغيل الذي يمكّنك من الاستمرار طويلاً. انتقل إلى الفصل السابع «الكلفة والحدود».

توسيعه — CLAUDE.md وhooks وsubagents وMCP