دعم ملف AGENTS.md في Claude Code: كيفية استخدامه مع CLAUDE.md

حصل Claude Code على دعم AGENTS.md في الإصدار v2.1.277: في المشروع الذي لا يحتوي على ملف CLAUDE.md، يقرأ Claude Code الآن ملف AGENTS.md بوصفه تعليمات المشروع. لا تحتاج إلى أي عملية استيراد أو رابط رمزي أو إعداد. وإذا كان مستودعك يحتوي على الملفين معًا، يقرأ Claude ملف CLAUDE.md فقط، ما لم تُغيّر إعداد Project instructions في /config ليقوم بتحميل الملفين.

إذا كان فريقك يستخدم مزيجًا من وكلاء البرمجة، فإن ملف AGENTS.md نفسه الذي يقرؤه Codex وCursor بالفعل يوجّه Claude Code الآن أيضًا. يغطي هذا الدليل ترتيب الأولوية، والترحيل، وطريقة إنشاء AGENTS.md يعلّم أي وكيل كيفية اختبار واجهات API لديك باستخدام Apidog CLI.

ما هو ملف AGENTS.md في Claude Code؟

AGENTS.md هو ملف Markdown بسيط يحتوي على تعليمات لوكلاء البرمجة: أوامر البناء، وأوامر الاختبار، وأسلوب الشيفرة، وقواعد المشروع. منذ الإصدار v2.1.277، يقرأ Claude Code هذا الملف عبر إضافة مدمجة، لذا فإن أي مستودع مُعد لوكلاء آخرين يعمل مع Claude Code دون الحاجة إلى ملفات إضافية. ولا يتطلب أي حقول إلزامية أو صيغة خاصة.

والصيغة نفسها مفتوحة. يصف موقع AGENTS.md هذا الملف بأنه "صيغة بسيطة ومفتوحة لتوجيه وكلاء البرمجة"، يستخدمها أكثر من 60,000 مشروع مفتوح المصدر، ويُدار الآن من قبل Agentic AI Foundation التابعة لـ Linux Foundation. كل من OpenAI Codex وCursor يوثّقان دعم AGENTS.md، وكان Claude Code هو الاستثناء الواضح حتى هذا الإصدار.

إذا كنت جديدًا على هذه الصيغة، ابدأ بـ كيفية كتابة ملفات AGENTS.md لفرق تطوير API.

وإليك تسلسل الإصدارات من سجل تغييرات Claude Code الرسمي:

شغّل claude --version قبل الاعتماد على أي مما سبق. في أي إصدار أقدم من 2.1.277، يقرأ Claude Code ملفات CLAUDE.md فقط.

CLAUDE.md مقابل AGENTS.md: أيهما يتفوق؟

افتراضيًا، يتفوق ملف CLAUDE.md. يقرأ Claude Code ملف AGENTS.md فقط عندما لا يوجد ملف CLAUDE.md في مجلد العمل الحالي أو أي مجلد أعلى منه. توضح وثائق ذاكرة Claude Code ثلاث حالات:

ليس كل ملف يُحتسب في هذا الفحص. الملفات الثلاثة التالية تحجب AGENTS.md:

• CLAUDE.md في مجلد العمل أو أعلى منه
• .claude/CLAUDE.md في مجلد العمل أو أعلى منه
• CLAUDE.local.md في مجلد العمل أو أعلى منه

أما هذه الملفات فلا تحجبه، وتظل تُحمَّل جنبًا إلى جنب مع AGENTS.md: ملف المستخدم الخاص بك في ~/.claude/CLAUDE.md، وملف CLAUDE.md المُدار من مؤسستك، والملفات الموجودة تحت .claude/rules/.

احذر من فخ CLAUDE.local.md: إذا أضفت ملفًا شخصيًا لملاحظات غير مُرسلة إلى Git، يتوقف Claude عن قراءة ملف AGENTS.md الخاص بالفريق بالنسبة لك.

ما الذي يحمّله Claude Code ومتى

عندما لا يوجد أي شيء يحجبه، يقرأ Claude Code:

1. عند بدء الجلسة: كل ملف AGENTS.md و.claude/AGENTS.md في مجلد العمل والمجلدات الأعلى منه. تطبع الجلسات التفاعلية سطرًا مثل no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md.
2. في المجلدات الفرعية: ملف AGENTS.md الخاص بالمجلد الفرعي، بمجرد أن يفتح Claude ملفًا فيه باستخدام أداة Read، شرط ألا يحتوي ذلك المجلد على ملف CLAUDE.md خاص به.
3. الاستيرادات: تُوسَّع استيرادات @path داخل AGENTS.md، وتُطبَّق أنماط claudeMdExcludes.

لا يقرأ Claude Code ملفات AGENTS.local.md أو AGENTS.override.md أو أي شيء تحت .agents/. إذا شاركت مستودعًا مع Codex، الذي يوثّق ملف AGENTS.override.md، فضع ذلك في اعتبارك.

كيفية تغيير ملفات التعليمات التي يحمّلها Claude Code

اكتب /config في إحدى الجلسات واضبط Project instructions على إحدى القيم الأربع التالية:

لمعظم الفرق المختلطة، يكون claude-md-and-agents-md هو الإعداد المناسب لك. فهو يحافظ على ملف CLAUDE.local.md الشخصي الخاص بك ويحمّل ملف AGENTS.md المشترك أيضًا.

يمكنك ضبطه في ملف إعدادات بدلًا من ذلك. يقرأ Claude Code هذا الإدخال من ~/.claude/settings.json، أو ملف --settings، أو الإعدادات المُدارة، ويتجاهله في ملفات إعدادات المشروع والإعدادات المحلية:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

قبل الإصدار v2.1.285 كان معرّف الإضافة agents-md@builtin. الإصدارات من 2.1.285 فصاعدًا تقبل كلا المعرّفين، لذا استخدم المعرّف القديم إذا كانت تثبيتات أقدم تشترك في الملف نفسه. ويسري التغيير بدءًا من رسالتك التالية.

إذا كان خيار Project instructions مفقودًا من /config، فجلستك غير قادرة على تحميل AGENTS.md: إما أنك على إصدار أقدم من 2.1.277، أو أنك عطّلت الإضافة المدمجة عبر /plugin، أو أنها أول جلسة لديك بعد الترقية (يعمل ذلك بدءًا من الجلسة التالية).

كيفية ترحيل حل بديل قديم لملف AGENTS.md

ربطت فرق كثيرة ملف AGENTS.md بـ Claude Code يدويًا قبل هذا الإصدار. توصي الوثائق بما يلي:

احتفظ باستيراد @AGENTS.md إذا كان أي شخص في فريقك لا يزال يستخدم إصدارًا أقدم من 2.1.277. فهو الإعداد الوحيد الذي يعمل على جميع الإصدارات.

استيراد أم رابط رمزي؟

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

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

إذا لم تكن بحاجة إلى أي شيء خاص بـ Claude، فإن الرابط الرمزي يفي بالغرض:

ln -s AGENTS.md CLAUDE.md

ثمة ملاحظتان مهمتان: أداتا Edit وWrite في Claude لن تكتبان عبر رابط رمزي، كما أن Git على Windows يسحب الرابط الرمزي المُودَع في المستودع كملف نصي من سطر واحد ما لم يكن core.symlinks مُفعّلًا. إذا كان أي شخص في فريقك يستخدم Windows، فاختر الاستيراد.

في كلتا الحالتين، شغّل /context all في جلستك التالية وتأكد من ظهور CLAUDE.md تحت Memory files.

ملف AGENTS.md واحد لـ Codex وCursor وClaude Code

المكسب الحقيقي هو مصدر حقيقة واحد. ضع أوامر البناء وأوامر الاختبار والاصطلاحات الخاصة بك في AGENTS.md في جذر المستودع، وسيقرأه Codex وCursor وClaude Code جميعًا.

بنية تعمل جيدًا في الواقع العملي:

• AGENTS.md في الجذر: كل ما يحتاجه كل وكيل. الأوامر، وخريطة المجلدات، وقواعد الأسلوب، وما يجب عدم المساس به.
• AGENTS.md في المجلدات الفرعية الكبيرة: قواعد تسري على تلك المجلدات فقط، مثل services/payments/AGENTS.md. يحمّل Claude Code هذه الملفات عند الطلب عندما يقرأ ملفًا في ذلك المجلد.
• ملف CLAUDE.md اختياري: فقط إذا كنت بحاجة إلى سلوك خاص بـ Claude، مثل وضع الخطة أو الخطّافات. ابدأه بـ @AGENTS.md.

ملاحظة واحدة: ملف AGENTS.md المُحمَّل عبر الإعداد لا يُشغّل خطّافات InstructionsLoaded، ولا يُحمَّل من المجلدات المضافة عبر --add-dir. إذا كنت تعتمد على أيٍّ من ذلك، فاستخدم مسار الاستيراد عبر @AGENTS.md.

علّم وكيلك اختبار واجهات API باستخدام Apidog CLI داخل AGENTS.md

اكتب قواعد اختبار API مرة واحدة، وأي وكيل يفتح المستودع سيشغّل الاختبارات بالطريقة نفسها. تمنح واجهة Apidog CLI الوكيل مخرجات JSON منظمة يستطيع قراءتها، فتبقى دورة العمل داخل الطرفية.

قم بالإعداد مرة واحدة على كل جهاز:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

اختصار مفيد: أخبر وكيلك "اقرأ https://apidog.com/apidog-cli-installation-guide.md وأعدّ Apidog CLI". ذلك الدليل مكتوب للوكلاء ويغطي التثبيت وتسجيل الدخول والمهارة.

ثم أضف قسمًا كهذا إلى ملف AGENTS.md الخاص بك:

## API testing (Apidog CLI)

- Apidog project ID: 123456. Staging environment ID: 7890.
- Never build Apidog JSON payloads from memory. Run
  `apidog cli-schema get <key>` first, then
  `apidog cli-schema validate <key> --file <path>`, and write only after it passes.
- After changing any handler under `src/routes/`, find its endpoint with
  `apidog endpoint list --project 123456` and its cases with
  `apidog test-case list --project 123456 --endpoint <endpointId>`.
- If a route has no test case, create one with
  `apidog test-case create --project 123456 --file case.json`.
- Run cases with
  `apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json`
  and summarize every failure before you say the task is done.
- Do not edit or delete endpoints in Apidog unless the task asks for it.

الآن، يكفي أمر واحد لإنجاز المهمة في Claude Code أو Codex أو Cursor:

I changed POST /orders to require a currency field. Update the Apidog test
case for it and run it against staging, following AGENTS.md.

يتبع الوكيل قواعدك ويشغّل أوامر مثل هذه:

apidog endpoint list --project 123456
apidog test-case list --project 123456 --endpoint <endpointId>
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json

كل علامة وردت أعلاه مأخوذة من apidog <cmd> --help في Apidog CLI الإصدار 2.2.12. السطر نفسه الخاص بـ apidog run مع -r junit يتكامل مع CI، و--upload-report يرسل ملخص التشغيل إلى التطبيق ليراها فريقك. للحصول على التفاصيل المتعلقة بجانب Claude Code، راجع كيفية استخدام Apidog CLI في Claude Code؛ ويمكن لمستخدمي Codex اتباع دليل Apidog CLI في Codex. تغطي النسخة المجانية Apidog Free حتى 4 مستخدمين، فيمكن لفريق صغير تجربة هذا اليوم.

استكشاف الأخطاء وإصلاحها: ملف AGENTS.md لا يُحمَّل عندي

1. ابحث عن CLAUDE.md على المسار. وجود ملف CLAUDE.md أو .claude/CLAUDE.md أو CLAUDE.local.md في مجلد العمل الحالي أو أعلى منه يمنحه الأولوية افتراضيًا. أما ~/.claude/CLAUDE.md الخاص بك فلا يُحتسب.
2. تحقق من إصدارك. شغّل claude --version. تحتاج إلى 2.1.277 أو أحدث، و2.1.281 أو أحدث على Bedrock أو Vertex AI أو Foundry أو بوابات LLM أو مع تعطيل القياس عن بُعد.
3. تحقق من الإعداد. افتح /config وتأكد من أن Project instructions ليس مضبوطًا على claude-md أو managed-only.
4. تأكد من تحميل الملف. شغّل /memory وابحث عن مسار AGENTS.md في القائمة.

الأسئلة الشائعة

هل يقرأ Claude Code ملف AGENTS.md الآن؟ نعم، بدءًا من الإصدار v2.1.277. في غياب CLAUDE.md في مجلد العمل الحالي أو أعلى منه، يقرأ Claude Code ملف AGENTS.md تلقائيًا بوصفه تعليمات المشروع.

إذا كان لدي ملف CLAUDE.md وAGENTS.md معًا، أيهما يستخدمه Claude Code؟ ملف CLAUDE.md فقط، افتراضيًا. اضبط Project instructions على claude-md-and-agents-md في /config لتحميل كليهما، مع أولوية CLAUDE.md.

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

هل يقرأ Claude Code ملف AGENTS.override.md كما يفعل Codex؟ لا. يتجاهل Claude Code ملفات AGENTS.override.md وAGENTS.local.md وأي شيء تحت .agents/.

هل يعمل ملف AGENTS.md على Amazon Bedrock أو Google Vertex AI؟ نعم، بدءًا من الإصدار v2.1.281. الإصدارات الأقدم على Bedrock أو Vertex AI أو Foundry أو بوابات LLM أو مع تعطيل القياس عن بُعد تقرأ CLAUDE.md فقط؛ استخدم استيراد @AGENTS.md هناك.