شرح Claude Code: كيف تفعّل قراءة AGENTS.md مباشرة

شرح Claude Code المختصر لتفعيل الميزة

اتبع هذا التسلسل:

1. شغّل claude --version. تحتاج إلى v2.1.277 أو أحدث.
2. حدّث الأداة عند الحاجة. يقبل التثبيت الأصلي الأمر claude update، بينما يستخدم Homebrew وWinGet أوامر الترقية الخاصة بكل مدير حزم.
3. تأكد من أن الجلسة تستطيع جلب أعلام الميزات من Anthropic. لا يتاح تحميل AGENTS.md الأصلي في جلسات المزوّدين الخارجيين مثل Amazon Bedrock وGoogle Cloud's Agent Platform وMicrosoft Foundry، ولا عندما تمنع إعدادات القياس عن بُعد أو حركة البيانات غير الضرورية جلب تلك الأعلام.
4. ضع AGENTS.md أو .claude/AGENTS.md في مسار المشروع. وفي الوضع الافتراضي، تأكد من عدم وجود CLAUDE.md للمشروع أو .claude/CLAUDE.md أو CLAUDE.local.md في دليل العمل أو أي دليل أعلى منه.
5. إذا كنت تحتاج إلى عائلتي الملفات معاً، افتح /config واضبط Project instructions على claude-md-and-agents-md.
6. اختبر في جلسة جديدة. الجلسة الأولى بعد التثبيت أو الترقية حالة استثنائية، لذا افتح الجلسة التالية قبل الحكم على النتيجة.

هذا هو المسار الأصلي. إذا لم يظهر خيار Project instructions في /config، فأبقِ استيراد @AGENTS.md الموثّق داخل CLAUDE.md.

كيف يختار Claude Code ملف التعليمات فعلياً؟

السلوك الجديد أشبه بلوحة تحويل، وليس فحصاً شاملاً لكل ملفات التعليمات. في الوضع الافتراضي claude-md-or-agents-md، يبحث Claude Code أولاً عن تعليمات Claude على مستوى المشروع. ولا يرجع إلى AGENTS.md إلا إذا لم يجد أياً من ملفات Claude المؤهلة في دليل العمل أو الأدلة الأعلى منه.

التفصيل الدقيق هنا هو النطاق. وجود CLAUDE.local.md في دليل أب يعطّل الرجوع الاحتياطي، بينما لا تفعل ذلك ملفات ~/.claude/CLAUDE.md الشخصية أو CLAUDE.md المُدارة من المؤسسة أو .claude/rules/. وهذا يفسّر كثيراً من الحالات التي يفتح فيها مطوّران المستودع نفسه ويحصلان على سلوك مختلف.

عندما تنطبق قاعدة الرجوع، يقرأ Claude Code ملفي AGENTS.md و.claude/AGENTS.md من دليل العمل والأدلة الأعلى منه عند بدء الجلسة. ويمكن تحميل AGENTS.md الموجود في دليل فرعي لاحقاً عندما يقرأ Claude ملفاً داخله، بشرط ألا يحتوي ذلك الدليل الفرعي على ملف Claude مؤهل خاص به. ولا يقرأ مباشرةً AGENTS.local.md أو AGENTS.override.md أو الملفات الموجودة تحت .agents/.

تخيّل الأمر كمفتاح اختيار كهربائي في مبنى، لا كعملية بحث في المجلدات. يختار المفتاح أولاً دائرة التعليمات النشطة؛ وقد تكون ملفات الدائرة الأخرى صحيحة تماماً، لكنها تظل غير موصولة.

اضبط وضع Project instructions بقرار مقصود

افتح /config، وابحث عن Project instructions، ثم اختر وفق المصدر الذي تريد اعتماده للحقيقة داخل المستودع:

• الرجوع الاحتياطي، claude-md-or-agents-md: الأنسب لمستودع يستخدم AGENTS.md بالفعل ولا يحتوي على ملف Claude للمشروع. وهذا هو الوضع الافتراضي.
• كلاهما، claude-md-and-agents-md: الأنسب عندما يضم AGENTS.md القواعد المشتركة ويضيف CLAUDE.md إرشادات خاصة بـ Claude.
• Claude فقط، claude-md: الأنسب عندما لا يكون الفريق مستعداً لإتاحة تعليمات الوكلاء المشتركة لـ Claude Code.
• المُدار فقط، managed-only: الأنسب لبيئة تشغيل منضبطة تُحمّل فيها سياسة المؤسسة والذاكرة التلقائية، من دون تعليمات المستودع عند بدء التشغيل.

في وضع العائلتين، يقرأ Claude Code محتوى Claude في كل دليل قبل محتوى AGENTS. كما يتجنب تحميل ملف AGENTS.md نفسه مرتين إذا كان CLAUDE.md يستورده بالفعل أو يشير إليه برابط رمزي.

يسري الاختيار ابتداءً من الرسالة التالية، ويستمر في الجلسات الجديدة. ويمكن أيضاً حفظه ضمن الإضافة المدمجة agents-md@builtin في إعدادات المستخدم، أو ملف --settings، أو الإعدادات المُدارة. يتجاهل Claude Code هذا الخيار في ملفات إعدادات المشروع والإعدادات المحلية، لذلك لا يستطيع المستودع فرض طريقة الاختيار نفسها خفيةً على كل مطوّر. ويمكن للمسؤول تحديد الخيار مركزياً عبر الإعدادات المُدارة.

كيف تثبت أي ملف حمّلته جلسة جديدة؟

استخدم معلومة اختبار غير ضارة، لا تعليمة قد تسبب أثراً جانبياً. أضف السطر التالي إلى الملف الذي تريد اختباره:

Project probe: BASALT-HERON.

بعد ذلك أغلق الجلسة، وابدأ الجلسة الجديدة التالية داخل المستودع، ثم اسأل: What is the project probe? ظهور الإجابة الصحيحة BASALT-HERON يثبت أن المحتوى وصل إلى سياق الجلسة. احذف السطر بعد انتهاء الاختبار.

لا تعتمد على /context وحده للحكم. فالملف AGENTS.md المحمّل مباشرةً لا يظهر في قائمة Memory files. وفي وضع الرجوع الافتراضي، قد تعرض الجلسة التفاعلية سطر بدء التشغيل AGENTS.md loaded. أما سؤال الاختبار غير الضار فيعمل أيضاً عبر أوضاع الاختيار الأخرى.

إذا فشل الاختبار، فتحقق من العناصر التالية بالترتيب:

1. النسخة: v2.1.277 أو أحدث.
2. تسلسل الجلسات: يجب ألا تكون هذه أول جلسة بعد التثبيت أو الترقية.
3. المزوّد: يجب ألا تكون الجلسة عبر مزوّد يمنع جلب أعلام الميزات من Anthropic.
4. البيئة: لا يوجد متغيّر للقياس عن بُعد أو لحركة البيانات غير الضرورية يعطّل ذلك الجلب.
5. الإضافة والسياسة: الإضافة المدمجة agents-md مفعّلة، ولا يحظرها disableAllHooks أو allowManagedHooksOnly.
6. هرمية الملفات: لا يوجد CLAUDE.md أو .claude/CLAUDE.md أو CLAUDE.local.md مؤهل في المستوى الحالي أو أي مستوى أعلى عند استخدام الوضع الافتراضي.
7. الوضع: يشير /config إلى السلوك الذي تقصده.

إذا لم يظهر Project instructions في /config، فهذه بحد ذاتها إشارة تشخيصية: إما أن الجلسة تعمل على نسخة غير مدعومة، أو أنها لا تستطيع استخدام الميزة.

احتفظ بالاستيراد حيث يتعذر تشغيل الدعم الأصلي

يظل الاستيراد الحالي طبقة التوافق الأكثر أماناً لجلسات Bedrock وVertex وFoundry وغيرها من المزوّدين الخارجيين، وللبيئات التي تقيّد القياس عن بُعد، وللفرق التي تستخدم نسخاً مختلفة. ضع السطر التالي في CLAUDE.md بجوار AGENTS.md:

@AGENTS.md

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

يعمل أيضاً إنشاء رابط رمزي من CLAUDE.md إلى AGENTS.md، لكن الاستيراد أكثر أماناً عبر المنصات. في Windows، قد يتطلب إنشاء الرابط الرمزي صلاحيات مرتفعة أو Developer Mode، كما يحتاج Git إلى إعداد الرابط الرمزي الصحيح. وإذا كان هناك خطاف SessionStart يطبع AGENTS.md، فينبغي إزالته بعد نجاح التحميل المباشر لأنه قد يحقن نسخة مكررة.

يغيّر هذا الإصدار حسابات الصيانة. قبل صدوره، كان الفريق الذي يعتمد سياسة واحدة مشتركة بين الوكلاء يحتفظ غالباً بملفين أو ملف استيراد وسيط أو خطاف. أما في الجلسات المدعومة، فيمكن أن يصبح المسار الافتراضي ملف تعليمات واحداً محفوظاً في المستودع. ولن تنخفض تكلفة ترخيص Claude: تدرج Anthropic خدمة Claude Code ضمن خطة Pro الشهرية البالغة $20. التوفير الحقيقي هو تقليل نقاط المزامنة وتقليل الجلسات التي تعمل بقواعد قديمة.

ولإكمال الإعداد، يشرح الدليل الأشمل لاستخدام Claude Code التثبيت وسياق المشروع وسير الأوامر اليومي. وإذا كان المستودع يعرّف وكلاء متخصصين أيضاً، فيغطي دليل الوكلاء الفرعيين سياق بدء التشغيل المنفصل الخاص بهم.

سبع حالات تظهر فيها قيمة هذا التغيير

رُتّبت الحالات التالية بحسب حجم مشكلة التنسيق التي يزيلها محدد التعليمات الجديد.

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

ما الذي يمكن بناؤه حول هذه الميزة؟

1. أداة تشخيص لتعليمات الوكلاء المتعددة

ابنِ أداة CLI محلية وفحصاً ضمن CI يشرحان بدقة ملفات التعليمات التي سيحمّلها كل وكيل برمجة. ستدفع فرق المنصات وشركات الاستشارات مقابل إجابة موثوقة قبل تعميم الإعداد على المستودعات.

الطلب ظاهر بالفعل: يحصد استعلام claude code setup نحو 1,900 عملية بحث شهرية في الولايات المتحدة، بينما يحصد claude md vs agents md نحو 480 عملية وقد نما 1,500% على أساس سنوي. أصغر نسخة قابلة للبيع تفحص شجرة الملفات، وتقرأ نسخة Claude Code وإعدادات المزوّد، وترصد الملفات التي تحجب غيرها، ثم تطبع خطة لترتيب التحميل. ويمكن لطبقة مدفوعة للفرق فرض السياسة نفسها عبر عدة مستودعات.

هذه أقوى فرصة لأنها تعالج مشكلة تشخيص، لا مشكلة قوالب. لكن الخطر هو الاعتماد على المنصة؛ فقد تدمج Anthropic هذه الفحوص داخل claude doctor. لذلك يحتاج المنتج المستدام إلى تغطية عدة وكلاء برمجة والاحتفاظ بسجل لاختلاف السياسات، لا الاكتفاء بأمر واحد من Claude.

2. أداة إنشاء وتدقيق سياسة AGENTS.md

ابنِ محرراً إرشادياً يحوّل أوامر البناء وقواعد الاختبار وحدود الأدلة ومتطلبات المراجعة إلى ملف AGENTS.md موجز، ثم يفحصه بحثاً عن التعارضات والصياغات المبهمة. المشتري هنا هو فريق هندسي صغير يتبنى عدة وكلاء.

يحصد agents md نحو 2,900 عملية بحث شهرية في الولايات المتحدة. أما الاستعلام الأدق agents md best practices فيحصد 210 عمليات وقد نما 750% على أساس سنوي. يحتاج المنتج الأولي إلى ماسح للمستودع، ومقابلة قصيرة، ومسودة مولّدة، وقواعد تدقيق تكشف التعليمات المكررة أو المتناقضة. وينبغي أن يلتزم بإرشادات المزوّد حول إيجاز ملفات المشروع بدلاً من إنتاج دليل سياسات ضخم.

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

3. تدقيق انتقال لأسطول مختلط من الوكلاء

قدّم تقريراً يرسم خريطة CLAUDE.md وAGENTS.md وعمليات الاستيراد والروابط الرمزية والخطافات والقواعد المتداخلة واستثناءات المزوّدين، ثم ينتج خطة انتقال آمنة إلى مصدر واحد. العملاء المرجحون هم الوكالات والفرق الأكبر التي تستخدم عدة أدوات للوكلاء.

تُعد عمليات البحث الشهرية البالغة 480 عن claude md vs agents md، مع نمو 1,500% على أساس سنوي، دليلاً مباشراً على هذا الالتباس. يمكن أن يكون المنتج الأولي محللاً للمستودع بوضع القراءة فقط، مع خطة لطلب سحب. وينبغي ألا يحذف أي جسر تلقائياً لأن الجلسات غير المدعومة قد تظل بحاجة إليه.

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

الحدود والتقييم الصريح

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

كما أن الميزة لا تجعل AGENTS.md ظاهراً في أدوات التشخيص نفسها التي تعرض CLAUDE.md. فالتحميل المباشر لا يظهر في /memory ولا في قائمة Memory files داخل /context. هذا التباين يجعل معلومة الاختبار غير الضارة جديرة بالبقاء في قائمة تحقق الانتقال.

لا تحذف استيراداً يعمل في أسطول يضم مزوّدين مختلفين لمجرد أن الاختبار نجح على حاسوب محمول واحد. ولا تختَر وضع العائلتين قبل مراجعة التعارضات. يُقرأ محتوى Claude قبل محتوى AGENTS داخل الدليل، لكن ترتيب السياق ليس نظاماً صارماً لأولوية السياسات.

مع ذلك، يظل الإصدار تحسيناً تشغيلياً مهماً. فالمستودع الذي يعتمد AGENTS.md بالفعل مصدراً مشتركاً يستطيع الآن العمل مع Claude Code من دون التظاهر بأن اسم الملف الثاني هو المصدر. إنها ميزة صغيرة ذات أثر كبير في التنسيق.

إذا كنت تريد نظام تعليمات موثوقاً لعدة وكلاء ومصمماً خصيصاً لمستودعاتك، يمكنني مساعدتك في هندسة الوكلاء وخطة التعميم.