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

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

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

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

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

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

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

المشهد حاليا مقسّم بحسب الأداة:

• CLAUDE.md هو ما يبحث عنه Claude Code.
• GEMINI.md هو عرف Gemini CLI.
• AGENTS.md هو المعيار العابر للأدوات، يقرأه Codex وغيره، وقد صُمّم ليكون الملف المحايد.

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

إن كنت تعمل غالبا داخل 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.md وGEMINI.md ملفين من سطر واحد يقولان "انظر AGENTS.md،" أو اربطهما برابط رمزي. مصدر واحد للحقيقة، وكل الأدوات مغذّاة.
• ملف واحد، مشترك بالاتفاق. إن كانت أدواتك تقبل التوجيه إلى مسار مخصص، فوجّهها كلها إلى AGENTS.md واحذف الباقي.

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

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

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

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

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

الخلاصة

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

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