كيف تكتب ملف AGENTS.md ليفهم أي وكيل برمجة بالذكاء الاصطناعي مشروعك

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

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

ملف AGENTS.md هو "ملف README للوكلاء": ملف Markdown بسيط تضعه في جذر مستودعك لتخبر أدوات البرمجة بالذكاء الاصطناعي بكيفية عمل مشروعك (agents.md). إنه ليس لغة إعدادات جديدة — فلا توجد حقول مطلوبة ولا صياغة خاصة. استخدم أي عناوين Markdown تشاء.

تكمن أهمية هذه الصيغة في أنها عابرة للأدوات حقاً. فحتى منتصف عام 2026 تُقرأ أصلياً من قِبل OpenAI Codex، و GitHub Copilot، و Cursor، و Windsurf، و Devin، و Aider، و Zed، و VS Code، و JetBrains Junie، وعشرات غيرها — أكثر من 28 أداة وأكثر من 60000 مستودع مفتوح المصدر (agents.md؛ Codersera). وهي الآن تحت رعاية مؤسسة Agentic AI Foundation التابعة لـ Linux Foundation، إلى جانب بروتوكول Model Context Protocol من Anthropic. كما يقرأ Claude Code ملف AGENTS.md أيضاً، وإن ظلّت صيغته الأصلية الأغنى هي CLAUDE.md (DeployHQ).

ملف واحد، ومعظم أدواتك تتصرف باتّساق.

لماذا يتفوّق الملف على تكرار نفسك في المحادثة

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

ماذا تضع فيه

فكّر في ما يحتاجه زميل فريق جديد كفؤ في يومه الأول — فهذا بالضبط ما يحتاجه الوكيل. أكثر الأقسام فائدةً هي:

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

كن محدداً. عبارة "اكتب شيفرة نظيفة" لا تعني شيئاً للوكيل. أما "استخدم pnpm لا npm؛ وشغّل pnpm test قبل الانتهاء؛ ولا تعدّل أبداً الملفات في src/generated/" فهي قابلة للتطبيق.

مثال ملموس

إليك ملف AGENTS.md مختصراً لتطبيق ويب نموذجي:

# AGENTS.md

## Project
Next.js 15 + TypeScript storefront. Package manager is pnpm.

## Setup & commands
- Install: `pnpm install`
- Dev server: `pnpm dev`
- Build: `pnpm build`

## Testing
- Run all tests: `pnpm test`
- All tests must pass before a task is considered done.

## Code style
- TypeScript strict mode; no `any`.
- Format with Prettier (`pnpm format`) — do not hand-format.
- Prefer named exports. Reuse helpers in `src/lib/` before writing new ones.

## Do not touch
- `src/generated/**` is auto-generated. Never edit by hand.
- Never commit `.env` files.

سلّم هذا الملف إلى Claude Code أو Cursor أو Copilot، وسيلتقط كلٌّ منها القواعد نفسها.

المستودعات أحادية المخزن (Monorepos): استخدم ملفات متداخلة

في المستودع أحادي المخزن يمكنك وضع ملف AGENTS.md في كل حزمة إضافةً إلى ملف في الجذر. وحين يعمل الوكيل داخل مجلد فرعي، يفوز الملف الأقرب (agents.md). أبقِ الأعراف المشتركة في الجذر، والأوامر الخاصة بكل حزمة في الملفات المتداخلة، بحيث يحصل الوكيل الذي يعدّل packages/api/ على أوامر البناء والاختبار الخاصة بتلك الحزمة تلقائياً.

AGENTS.md مقابل CLAUDE.md مقابل قواعد Cursor

قد يكون لديك بالفعل ملفات خاصة بأدوات معيّنة مثل CLAUDE.md أو .cursor/rules. ولست مضطراً للتخلّص منها. عملياً، تضع الفرق الأعراف المشتركة غير المرتبطة بأداة معيّنة في AGENTS.md — الأشياء التي يحتاجها كل وكيل — وتبقي الإضافات الخاصة بأداة معيّنة في الملف الأصلي للأداة التي تدعم ميزات أغنى (DeployHQ). فـ Claude Code مثلاً يقرأ كليهما، مع CLAUDE.md بوصفه صيغته الأكثر تعبيراً. ومن الأنماط الشائعة الاحتفاظ بملف AGENTS.md واحد كمرجع معياري، وحيثما احتاجت أداة إلى ملفها الخاص، توجيه ذلك الملف إلى AGENTS.md لتبقى هناك نقطة حقيقة واحدة. ابدأ بـ AGENTS.md؛ ولا تلجأ إلى الملف الخاص بالأداة إلا حين تحتاج إلى ميزة تدعمها هي وحدها.

أبقِه قصيراً ومحدداً

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

كيف تبقيه مفيداً

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