AGENTS.md: ملف سياق واحد لكل وكيل برمجة (Codex وAntigravity وClaude)

قضيت بعد ظهر يوم كامل في كتابة ملف CLAUDE.md نظيف. وأخيرا توقف وكيلك عن تخمين حزمتك التقنية وبدأ يشغّل أمر الاختبار الصحيح. ثم يفتح زميل في الفريق المستودع نفسه باستخدام Codex، وتجرّب أنت Antigravity CLI على فرع جانبي، فإذا بكل هذا السياق الذي اكتسبته بشق الأنفس لا ينتقل معك. كل أداة تريد ملفها الخاص، في مكانها الخاص.

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

ما هو AGENTS.md فعليا

لا سحر في الأمر. إنه ملف Markdown يحمل اسم AGENTS.md، يوضع عادة في جذر المستودع، يحمّله الوكيل بوصفه تعليمات ثابتة قبل أن يبدأ العمل. تخيله بمثابة ملف README الذي تكتبه لزملائك من وكلاء الذكاء الاصطناعي بدلا من زملائك من البشر: ما هو المشروع، وكيف تبنيه وتختبره، والأعراف الواجب احترامها، والمطبات الواجب تجنبها.

إنه عرف مفتوح، يقرأه Codex بالفعل وقائمة متنامية من أدوات الوكلاء، وقد صُمّم بهدف صريح هو أن يكون محمولا بينها. ملف واحد لوكلاء كثيرين، بدلا من ملف مفصّل خصيصا لكل أداة.

AGENTS.md مقابل CLAUDE.md مقابل GEMINI.md

حين كُتب هذا الدليل أول مرة، كانت كل أداة تبحث عن ملفها الخاص. ومنذ ذلك الحين اتجهت معظمها نحو AGENTS.md:

• Codex يقرأ AGENTS.md، وكذلك GitHub Copilot CLI وCursor وAmp ومعظم وكلاء CLI الأحدث.
• Claude Code يقرأ CLAUDE.md، ومنذ الإصدار 2.1.277 صار يقرأ AGENTS.md أيضا من تلقاء نفسه حين لا يحتوي مجلد العمل لديك والمجلدات التي فوقه على CLAUDE.md ولا CLAUDE.local.md. وحين يوجد CLAUDE.md، لا يقرأ Claude سوى هذا الملف، ما لم تغيّر الإعداد Project instructions في /config.
• Antigravity CLI يقرأ AGENTS.md أو GEMINI.md، في جذر المستودع أو في أي مجلد فرعي، إضافة إلى مجلد .agents/rules/ وقواعد عامة تحت ~/.gemini/.

المحتوى متطابق تقريبا في الثلاثة: سياق المشروع، والأوامر، والأعراف. أما ما زال مختلفا فهو الملف الذي تختاره الأداة حين تجد أكثر من ملف. ولهذا بالضبط فإن تكرار القواعد نفسها يدويا في ثلاثة ملفات معركة خاسرة سلفا (سنعود أدناه إلى كيفية إبقائها متزامنة). تحققنا من هذه السلوكيات في 10 أكتوبر 2026 بالرجوع إلى توثيق الذاكرة في Claude Code وتوثيق القواعد في Antigravity.

إن كنت تعمل غالبا داخل Claude Code، فإن دليل CLAUDE.md يتعمق في البنية الخاصة بـ Claude. أما AGENTS.md فهو الشقيق المحايد لذلك الملف، المستقل عن المزوّد.

ماذا تضع فيه

أبقه قصيرا وعالي الإشارة. يقرأه الوكيل في كل مهمة، فكل سطر يتنافس على الانتباه. الأساسيات:

• الحزمة التقنية في نفَس واحد. "Next.js 16, TypeScript, Prisma, MariaDB." بلا تاريخ، بلا تسويق.
• الأوامر التي تهم. كيف تثبّت وتشغّل وتبني وتختبر وتفحص الشيفرة. أوامر دقيقة: npm test، لا "شغّل الاختبارات."
• الأعراف. التسمية، وتنظيم الملفات، ومعالجة الأخطاء، والأنماط التي تفرضها فعلا في المراجعة.
• خريطة للمجلدات. سطران عن مكان وجود الأشياء، حتى يتوقف الوكيل عن البحث الأعمى بـ grep.
• قواعد "اقرأ قبل أن تلمس". "اقرأ docs/payments.md قبل تعديل أي شيء تحت billing/." هذه العادة وحدها تمنع كثيرا من الأضرار.
• الممنوعات القاطعة. "لا تنشئ فرعا أبدا من دون أن يُطلب منك." "لا مسارات مطلقة مرتبطة بالجهاز في الملفات المُودعة."

الأخطاء التي تجعل الوكلاء يتجاهلونه

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

1. مفرط الطول. ملف من 600 سطر يدفن القواعد الخمس التي تهم. احذف كل ما يستطيع الوكيل استنتاجه من الشيفرة نفسها.
2. التناقضات. "اكتب الاختبارات دائما" في قسم، و"تخطَّ الاختبارات في النماذج الأولية" في قسم آخر. يختار الوكيل واحدا منهما عشوائيا.
3. مسارات خاصة بالجهاز. /Users/you/project/... في ملف مُودع يتعطّل لدى كل زميل، ولدى كل وكيل على أي جهاز آخر. أبقِ المسارات نسبية.
4. أوامر بائتة. تغيّر أمر الاختبار قبل ستة أشهر، ولم يتغيّر الملف. والآن يشغّل الوكيل الأمر الخطأ بثقة تامة.
5. غياب الأولويات. كل شيء "مهم،" فلا شيء مهم إذن. ضع غير القابل للتفاوض في المقدمة وميّزه بوسم.
6. إغراق بالتوثيق. هذه تعليمات، لا موسوعة. ضع روابط إلى توثيقك، ولا تلصقه بداخله.

الحفاظ على سياق واحد عبر المزوّدين

هنا الجزء العملي الذي تتخطاه معظم الأدلة. إن كنت أنت، أو فريقك، تشغّلون أكثر من وكيل CLI، فأنت لا تريد ثلاث نسخ متباعدة من القواعد نفسها.

نهجان نظيفان:

• ملف AGENTS.md واحد، ولا شيء غيره. إن لم يكن أحد بحاجة إلى قواعد تخص Claude وحده، فاحتفظ بملف AGENTS.md واحد: يقرأه Codex وAntigravity CLI وClaude Code 2.1.277 أو أحدث جميعا. لكن الفخ صامت: ملف CLAUDE.md، أو ملف CLAUDE.local.md شخصي، يُضاف لاحقا يجعل Claude Code يتوقف عن قراءة AGENTS.md.
• ملف مرجعي واحد، واستيراد واحد. ضع كل شيء في AGENTS.md وابدأ CLAUDE.md بالسطر @AGENTS.md، ثم اكتب تحته القواعد الخاصة بـ Claude وحده. يقرأ Claude الملف المستورد أولا. مستودعنا نحن يعمل بهذه الطريقة: ملف CLAUDE.md فيه هو هذا السطر الواحد. الرابط الرمزي (ln -s AGENTS.md CLAUDE.md) يعمل أيضا، لكن ليس جيدا على Windows، حيث يتطلب إنشاؤه امتيازات المسؤول أو وضع المطور، وحيث يحصل أي استنساخ من دون core.symlinks على ملف نصي من سطر واحد بدلا من تعليماتك.

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

حين تشغّل عدة وكلاء في آن واحد

يجيب AGENTS.md على مستوى المستودع عن سؤال "ما هذا المشروع." لكنه لا يجيب عن سؤال "من هذا الوكيل." حين تشغّل وكيل Backend ووكيل Frontend ووكيل QA بالتوازي على الشيفرة نفسها، يحتاج كل منهم إلى سياق المشروع المشترك إضافة إلى دوره الخاص.

هذه هي الطبقة التي يضيفها AgentsRoom فوق ملف AGENTS.md لديك. يحصل كل وكيل على دور مخصص مع موجّه نظام خاص به (DevOps وFrontend وأمن وغيرها)، فيبقى الملف المشترك خفيفا بينما يظل كل وكيل عارفا بمهمته. وهو مستقل عن المزوّد بحكم تصميمه، فالإعداد نفسه يشغّل Claude أو Codex أو Antigravity جنبا إلى جنب، وتعليماتك القابلة لإعادة الاستخدام تعيش في مكتبة موجّهات بدلا من إعادة كتابتها في كل جلسة.

حين تبلغ هذه النقطة، تكون طريقة تشغيل عدة وكلاء بالتوازي من دون أن تفقد زمام الأمور هي القراءة التالية الطبيعية.

الخلاصة

اكتب ملف AGENTS.md واحدا. أبقه قصيرا، أبقه محدّثا، أبقه محمولا. وجّه كل أداة إليه بدلا من صيانة ملف لكل وكيل. عندها يتوقف سياقك عن الارتباط بأي CLI صادف أن بدأت به، ويبدأ وكلاؤك، أيا كانوا، من النقطة نفسها.

أتريد كل وكيل على شاشة واحدة، لكل منه دوره وسياقك المشترك؟ حمّل AgentsRoom، وصِل مزوّدك، وضع أسطولك في العمل.

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

ما هو AGENTS.md؟

ملف Markdown، يوضع عادة في جذر المستودع، تحمّله وكلاء البرمجة بوصفه تعليمات ثابتة قبل أن تبدأ العمل: ما هو المشروع، وكيف تبنيه وتختبره، والأعراف الواجب احترامها، والمطبات الواجب تجنبها. إنه عرف مفتوح مشترك بين الأدوات وليس ملفا خاصا بأداة واحدة، يقرأه Codex وAntigravity CLI وGitHub Copilot CLI وCursor وAmp، وكذلك Claude Code منذ الإصدار 2.1.277.

هل يقرأ Claude Code ملف AGENTS.md؟

نعم، منذ Claude Code 2.1.277، لكن فقط حين لا يوجد CLAUDE.md ولا .claude/CLAUDE.md ولا CLAUDE.local.md في مجلد العمل لديك أو فوقه. عندها يحمّل كل ملف AGENTS.md من مجلد العمل صعودا، وملف AGENTS.md الخاص بمجلد فرعي حين يفتح ملفا فيه. إن وُجد CLAUDE.md، لا يقرأ Claude سوى هذا الملف، ما لم تضبط Project instructions على claude-md-and-agents-md في /config. في الإصدارات الأقدم، ضع السطر @AGENTS.md في أعلى ملف CLAUDE.md.

هل يستخدم Antigravity ملف AGENTS.md أم GEMINI.md؟

كلاهما. يقرأ Antigravity ملف AGENTS.md أو GEMINI.md أو مجلد .agents/rules/ في جذر المستودع أو في أي مجلد فرعي، وقواعد عامة من ~/.gemini/. تتراكم القواعد بدلا من أن يحل بعضها محل بعض، وحين تتعارض قاعدتان، تغلب قاعدة المجلد الأكثر تحديدا.

هل أحتفظ بـ AGENTS.md أم بـ CLAUDE.md؟

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

أين أضع AGENTS.md؟

في جذر المستودع للقواعد التي تسري في كل مكان. يقرأ Claude Code وAntigravity أيضا ملفات AGENTS.md الموجودة في المجلدات الفرعية، لذا يمكن لحزمة أو خدمة لها أوامرها الخاصة أن تحمل ملفها الخاص، يُقرأ حين يعمل الوكيل في ذلك المجلد.