ملف AGENTS.md هو "ملف README لوكيل البرمجة" بصيغة Markdown خالصة، يوجد في جذر مستودعك ويُخبر أدوات مثل Claude Code وCodex وCursor بكيفية البناء والاختبار والتصرف داخل مشروعك. أفضل هذه الملفات قصيرة ومحددة ومكتوبة يدويًا: تُدرج أوامرك الدقيقة، وتذكر حزمتك التقنية مع الإصدارات، وترسم حدودًا صارمة حول ما يجب على الوكيل ألا يمسّه أبدًا. أما أسوأها فطويلة وغامضة ومُولَّدة آليًا — وهناك الآن أدلة مقيسة على أنها تجعل الوكلاء أبطأ وأقل دقة.
نحن نبني TechRiseUps باستخدام Claude Code، وكان الملف الوحيد الذي غيّر أكثر من غيره مدى موثوقية إنجازه للعمل الصحيح هو ملف تعليمات الوكيل. هذا هو الدليل العملي الذي كنا نتمنى أن يكون بين أيدينا: ماذا تكتب، وماذا تحذف، ولماذا القليل أفضل.
ما هو ملف AGENTS.md؟
AGENTS.md هو صيغة مفتوحة ومحايدة تجاه الأدوات لتوجيه وكلاء البرمجة — "مكان مخصص ويمكن التنبؤ به لتوفير السياق والتعليمات التي تساعد وكلاء البرمجة الذكيين على العمل على مشروعك". فكّر فيه بوصفه نظيرًا لملف README الموجّه للبشر: خطوات البناء وأوامر الاختبار والأعراف التي قد تُثقل ملف README لكن الوكيل يحتاجها فعلًا.
كانت OpenAI رائدة هذه الصيغة من أجل Codex، وفي ديسمبر 2025 جرى التبرع بها إلى مؤسسة الذكاء الاصطناعي الوكيلي (Agentic AI Foundation) تحت مظلة Linux Foundation، فلم تعد عرفًا خاصًا بمزوّد واحد. وهي معترف بها الآن من أكثر من 60,000 مشروع مفتوح المصدر ومدعومة عبر أكثر من 28 أداة تشمل Codex وCursor وAider وDevin وGoogle Jules وVS Code. يقرأ Claude Code ملفه الخاص CLAUDE.md ويحترم بشكل متزايد AGENTS.md أيضًا؛ والنصائح المتعلقة بالمحتوى أدناه تنطبق على كليهما. ملف واحد، وكلاء كثيرون — تلك هي الفكرة كلها.
ماذا تضع في ملف AGENTS.md
حلّلت GitHub أكثر من 2,500 ملف agents.md حقيقي (نُشر في 19 نوفمبر 2025) ووجدت انقسامًا واضحًا بين الملفات التي تساعد والملفات التي تُتجاهَل. تشترك الملفات الفاشلة في سمة واحدة: إنها غامضة جدًا. فشخصيات "المساعد البرمجي المفيد" لم تُجدِ نفعًا؛ بينما أنجزت الأوامر الدقيقة والحدود الصارمة العمل.
إليك ما يستحق مكانه — وما ينبغي إسقاطه:
| ضمّنه (يستحق ما يستهلكه من رموز) | احذفه (يُهدر الرموز) |
|---|---|
أوامر دقيقة مع الرايات: pnpm test، pytest -v | "شغّل الاختبارات" دون أمر |
| الحزمة التقنية مع الإصدارات: "React 18، TS 5، Vite، Tailwind" | "حزمة ويب حديثة" |
| مقتطف كود حقيقي يوضّح أسلوبك | فقرات تصف أسلوبك |
| حدود ثلاثية المستويات: دائمًا / اسأل أولًا / أبدًا | سطر عام مثل "كن حذرًا" |
| مطبّات غير بديهية (خصوصيات monorepo، إعداد البيئة) | شجرة أدلة كاملة يستطيع الوكيل قراءتها بنفسه |
| "لا تُودِع الأسرار أبدًا" والمسارات المحمية | إعادة سرد توثيق اللغة الذي يعرفه النموذج أصلًا |
كان القيد الأكثر شيوعًا والمفيد حقًا عبر المستودعات الـ 2,500 صريحًا: "لا تُودِع الأسرار أبدًا". هذا السطر الواحد هو أرخص تأمين يمكنك كتابته، وهو يرتبط مباشرة بالدروس الأوسع لسلسلة التوريد المستفادة من أزمة npm Shai-Hulud — إذ يمكن للوكلاء الذين يملكون وصولًا إلى الطرفية تسريب بيانات الاعتماد بنفس سرعة حزمة مخترقة.
لماذا يتفوق ملف AGENTS.md الأقصر على الأطول
هذا هو الجزء الذي تتجاهله معظم الأدلة، وهو الأهم. يُحقن كل سطر في ملف AGENTS.md لديك في كل جلسة للوكيل، لذا فإن كل سطر ينافس على ميزانية الانتباه المحدودة للنموذج. حشوه بالمزيد لا يساعد الوكيل — بل يضره فعليًا.
وضعت دراسة من ETH Zurich عام 2026 أرقامًا على ذلك. فقد خفّضت ملفات السياق المُولَّدة آليًا والمنتفخة نجاح المهام في 5 من أصل 8 إعدادات مُختبَرة، وجعلت الوكلاء يتخذون من 2.45 إلى 3.92 خطوة إضافية لكل مهمة، ورفعت تكاليف الاستدلال بنسبة 20–23% — وكل ذلك دون إضافة أي جودة قابلة للقياس. في المقابل، تفوّقت الملفات المُنسَّقة يدويًا على تلك المُولَّدة بواسطة نماذج اللغة الكبيرة لكل وكيل جرى اختباره، بنحو 4 نقاط مئوية على معيار AGENTbench. وعندما حذف الباحثون التوثيق الزائد تمامًا، تحسّن أداء الملفات المُولَّدة آليًا فعلًا، ما يؤكد أنها كانت في الغالب تكرّر أشياء يعرفها النموذج أصلًا.
تتطابق القاعدة العملية لدى الممارسين مع البيانات: اجعله قصيرًا. والإجماع العام هو أقل من 300 سطر، وفرق مثل HumanLayer تُبقي ملفها تحت 60 سطرًا. اكتبه بنفسك، وعن قصد، لأن "سطرًا سيئًا في AGENTS.md يتتالى إلى خطط سيئة وكود سيء ونتائج سيئة عبر كل جلسة".
كيف تكتب ملف AGENTS.md خطوةً بخطوة
يمكنك امتلاك ملف يعمل في عشر دقائق. افعل ذلك بهذا الترتيب:
- أنشئ
AGENTS.mdفي جذر المستودع. ابدأ فارغًا. قاوم الرغبة في تشغيل أمر "ولّد لي AGENTS.md" — فأنت تعرف الآن أن البيانات تقول إن المكتوب يدويًا هو الفائز. - اكتب الأوامر أولًا. الأسطر الدقيقة التي ستكتبها للتثبيت والتشغيل والاختبار والفحص اللغوي (lint). ضمّن الرايات. هذا هو القسم الأعلى قيمة، لذا يأتي في الأعلى.
- اذكر الحزمة التقنية مع الإصدارات. سطر واحد: اللغات، إطار العمل، مدير الحزم، المكتبات الرئيسية وإصداراتها الكبرى. الغموض هنا يسبّب أكثر خطوات الوكيل المُهدَرة.
- أضِف مقتطف كود حقيقيًا واحدًا يوضّح أعرافك — دالة أو مكوّنًا فعليًا من مستودعك، لا وصفًا لهما.
- حدّد حدودًا ثلاثية المستويات. دائمًا (مثل "شغّل أداة الفحص اللغوي قبل الإنهاء")، اسأل أولًا (مثل "قبل تغيير مخطط قاعدة البيانات")، أبدًا (مثل "لا تُودِع الأسرار أبدًا، ولا تمسّ
/vendorأبدًا، ولا تشغّلgit pushأبدًا"). هنا تُرمِّز الحكم الذي لا يستطيع النموذج استنتاجه. - دوّن غير البديهي فقط. تخطيط حزم monorepo، متغير بيئة مطلوب، اختبار متقلب يجب تجاهله. تخطَّ أي شيء يستطيع الوكيل اكتشافه بقراءة شجرة الأدلة.
- اختبره، ثم قلّمه. شغّل مهمة حقيقية، وراقب أين يخمّن الوكيل خطأً، وأضِف سطرًا لإصلاح ذلك، واحذف أي سطر لم يستحق مكانه قط.
مردود واحد يخالف الحدس: الأدوات التي تذكرها في AGENTS.md تُستخدَم نحو 160 مرة أكثر من الأدوات التي لا تذكرها. إن أردت أن يستخدم الوكيل سكربتك المخصص أو خادم MCP محددًا، فاذكره صراحةً — وإلا فهو فعليًا غير موجود. وإذا كنت لا تزال تختار الوكيل الذي ستعتمده معيارًا، فإن مواجهتنا بين Cursor وCopilot وWindsurf وClaude Code لعام 2026 تغطي كيف يُحمّل كلٌّ منها سياق المشروع.
AGENTS.md وCLAUDE.md و.cursorrules — هل تحتاج الثلاثة جميعًا؟
لا. AGENTS.md هو المعيار الناشئ العابر للأدوات، لذا اجعله مصدر الحقيقة لديك. لا يزال Claude Code يبحث عن CLAUDE.md، وكان Cursor يستخدم .cursorrules تاريخيًا؛ والخطوة الأقل جهدًا هي إبقاء المحتوى الحقيقي في AGENTS.md، وحيثما تُصرّ أداة على اسم ملفها الخاص، اربطه رمزيًا (symlink) أو استوردْه بدلًا من صيانة نسختين متباعدتين. وفي monorepo، يمكنك أيضًا تعشيش الملفات: يقرأ الوكلاء تلقائيًا أقرب ملف AGENTS.md في شجرة الأدلة، بحيث يمكن لحزمة أن تتجاوز الجذر — إذ يشحن مستودع OpenAI نفسه 88 منها. أبقِ ملف الجذر عامًا ودَعْ كل حزمة تحتفظ بخصوصياتها. ويظل الوكيل الذي تقرنه به مهمًا؛ راجع تجميعتنا عن أفضل أدوات البرمجة بالذكاء الاصطناعي في 2026.
أخطاء شائعة يجب تجنّبها
- توليد الملف بأكمله آليًا. أسرع طريق إلى وكيل أبطأ. ولّد هيكلًا على أقصى تقدير، ثم أعِد كتابته يدويًا.
- لصق شجرة أدلتك. الوكلاء يُدرجون الملفات بأنفسهم؛ والشجرة الساكنة تتعفّن وتحرق الرموز فحسب.
- إعادة ذكر الواضح. يعرف النموذج كيف تعمل Python. أخبره بما هو خاص بمستودعك.
- ملف واحد عملاق لكل شيء. استخدم الكشف التدريجي: احتفظ بالملاحظات الخاصة بمهام معينة في مستندات منفصلة (مثل
agent_docs/running-tests.md) وأشِر إليها، ليبقى ملف الجذر رشيقًا. - عدم مراجعته مطلقًا. ينحرف الملف مع تغيّر مشروعك. قلّمه كلما خمّن الوكيل خطأً.
الأسئلة الشائعة
أين يوضع ملف AGENTS.md؟
في جذر مستودعك. أما بالنسبة إلى monorepos، فأضِف ملفات AGENTS.md إضافية داخل الحزم الفردية؛ يقرأ الوكيل أقربها إلى الملف الذي يعمل عليه، ولذلك الملف الأقرب الأولوية.
ما الطول الذي ينبغي أن يكون عليه ملف AGENTS.md؟
قصير. الإجماع العملي هو أقل من 300 سطر، والكثير من الأمثلة القوية تقبع تحت 100 سطر. ولأن كل سطر يُحمّل في كل جلسة، فإن للطول تكلفة حقيقية في الدقة والرموز معًا — اكتب فقط ما يغيّر سلوك الوكيل.
هل ينبغي أن أدَع ذكاءً اصطناعيًا يولّد ملف AGENTS.md؟
استخدم واحدًا لصياغة هيكل تقريبي إن كان لا بد، لكن لا تشحنه كما هو. وجدت أبحاث ETH Zurich أن الملفات المُولَّدة آليًا خفّضت نجاح المهام في معظم الإعدادات ورفعت التكاليف بنسبة 20–23%. وتفوّقت الملفات المُنسَّقة يدويًا على المُولَّدة في كل المجالات — فالملف يستحق أن يُكتب يدويًا.
هل يستخدم Claude Code ملف AGENTS.md؟
يقرأ Claude Code ملف CLAUDE.md أصالةً، ويعترف بشكل متزايد بـ AGENTS.md. ومبادئ المحتوى متطابقة في كلتا الحالتين: أوامر دقيقة، حزمة تقنية مع الإصدارات، حدود صارمة، وإيجاز. إن كنت تحتفظ أصلًا بملف CLAUDE.md جيد، فأنت على بُعد 90% من ملف AGENTS.md جيد.
ما الشيء الوحيد الذي يجب أن يحتويه كل ملف AGENTS.md؟
حدّ "أبدًا" يتضمّن "لا تُودِع الأسرار أبدًا". فقد كان القيد المفيد الأكثر شيوعًا على الإطلاق عبر أكثر من 2,500 مستودع حقيقي، وهو أرخص سطر يحمي قاعدة كود صار بإمكان الوكيل تحريرها وتشغيلها.
المصادر
- agents.md — الصيغة والمواصفة المفتوحة: التعريف، الأدوات المدعومة، تعشيش monorepo، ورعاية Agentic AI Foundation / Linux Foundation.
- مدوّنة GitHub — كيف تكتب ملف agents.md رائعًا: دروس من أكثر من 2,500 مستودع: الأقسام المدعومة بالبيانات التي تنجح ونمط الفشل "الغامض جدًا" (19 نوفمبر 2025).
- Philipp Schmid — كتابة ملف AGENTS.md جيد: إجماع "أبقِه تحت 300 سطر" واكتشاف زيادة استخدام الأداة 160 مرة عند ذكرها.
- Augment Code — كيف تبني ملف AGENTS.md الخاص بك: ملخّص دراسة ETH Zurich التي تُظهر أن الملفات المُولَّدة آليًا تخفّض نجاح المهام وترفع التكلفة.
وقاص احمد وسیر
وقاص احمد وسیر مطوّر ومهندس أتمتة بخبرة تزيد على 8 سنوات في بناء أنظمة إنتاجية يستخدمها أكثر من 100 ألف شخص. يبني تطبيقات SaaS متعددة المستأجرين، وأتمتة بالذكاء الاصطناعي (n8n، تدفقات LLM، بوتات واتساب)، وبنية استضافة (WHM/cPanel، CloudLinux) — وهو صانع WaSphere وFlowMaticX وعلامة الاستضافة WaseerHost. أنجز أكثر من 100 مشروع لشركات صغيرة ومتوسطة ووكالات وشركات ناشئة ممولة.
