دليل عملي: اكتب ملف AGENTS.md وموجز المهمة قبل أن تسلّم مشروعك لوكيل برمجة

إذا سلّمت مشروعك لوكيل برمجة بالذكاء الاصطناعي دون تعليمات مكتوبة، فأنت تطلب منه أن يخمّن: أي أوامر يشغّل، وأي ملفات لا يلمسها، وما معنى «انتهيت». والتخمين في الكود مكلف.

الحل ليس طلبًا أطول في نافذة المحادثة، بل طبقتان مكتوبتان:

1. ملف تعليمات دائم داخل المستودع، يقرؤه الوكيل في بداية كل جلسة، واسمه الشائع اليوم AGENTS.md.
2. موجز مهمة لكل ميزة: ما المطلوب، وما الممنوع، ومتى نعتبر العمل منتهيًا.

هذا الدليل يشرح الطبقتين خطوة بخطوة.

ما هو ملف AGENTS.md؟

بحسب موقعه الرسمي، هو صيغة مفتوحة وبسيطة لتوجيه وكلاء البرمجة، ويشبه ملف README لكنه موجه للوكلاء: مكان ثابت ومتوقع لأوامر البناء والاختبار وقواعد الكود. وهو ملف Markdown عادي بلا حقول إلزامية. نشأت الصيغة بجهد مشترك بين عدة أدوات، منها Codex من OpenAI وCursor وJules من جوجل، وتشرف عليها اليوم مؤسسة Agentic AI Foundation تحت مظلة مؤسسة لينكس.

قاعدتان مهمتان من توثيقها:

• الأقرب يفوز: في المشاريع الكبيرة يمكن وضع ملف داخل كل مجلد فرعي، والملف الأقرب إلى الملف الذي يُعدَّل له الأولوية.
• طلبك الصريح في المحادثة يتقدم على كل شيء: التعليمات المكتوبة أساس، والطلب المباشر يتجاوزها.

ويذكر الموقع أن الوكيل سيحاول تشغيل أوامر الاختبار المذكورة في الملف وإصلاح الأخطاء قبل أن ينهي المهمة. أي أن سطرًا مثل «شغّل الاختبارات» ليس تفصيلًا تجميليًا.

كيف تقرؤه الأدوات المعروفة؟

أداة Codex من OpenAI: تقرأ الملف قبل أي عمل. تبدأ بملف عام في مجلد المستخدم، ثم تنزل من جذر المشروع حتى المجلد الحالي، وتدمج الملفات بحيث يأتي الأقرب في النهاية فيتقدم على غيره. وهناك حد افتراضي لحجم التعليمات المدمجة قدره ٣٢ كيلوبايت، ويمكن تعديله من الإعدادات.

أداة Claude Code من Anthropic: ملفها الأصلي اسمه CLAUDE.md، لكنها بحسب توثيقها تقرأ AGENTS.md عندما لا يوجد CLAUDE.md في المشروع. وإذا احتجت الملفين معًا، فالطريقة الموصى بها أن يحتوي CLAUDE.md على سطر الاستيراد @AGENTS.md، حتى يبقى للمشروع مصدر واحد للتعليمات.

إطار Next.js: من الإصدار ١٦٫٣، يولّد الأمر next dev ملفي AGENTS.md وCLAUDE.md تلقائيًا إذا اكتشف وكيل برمجة في البيئة، ويضع فيهما تنبيهًا بقراءة التوثيق المرفق مع الحزمة نفسها بدل الاعتماد على معرفة الوكيل التي قد تكون قديمة.

ومستودع هذا الموقع مثال حي على ذلك: فيه ملف AGENTS.md بالكتلة التي يولّدها الإطار، وملف CLAUDE.md من سطر واحد هو @AGENTS.md.

ماذا تكتب في الملف؟

ابدأ صغيرًا، بما يحتاجه زميل جديد في يومه الأول:

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

مثال مختصر بالإنجليزية، لأن الأوامر نفسها بالإنجليزية:

# AGENTS.md
## Commands
- Install: npm ci
- Test: npm test
- Build: npm run build
## Rules
- Arabic is first-class: every page ships in ar (RTL) and en.
- Never commit secrets or edit deployment settings.
- Do not invent numbers, users, or testimonials in UI copy.

ونصيحتان من توثيق Claude Code تنطبقان على أي أداة:

• اكتب تعليمات قابلة للتحقق: «شغّل أمر الاختبار قبل الحفظ» أوضح من «اختبر تغييراتك».
• أبقِ الملف قصيرًا: يقترح التوثيق أقل من ٢٠٠ سطر للملف الواحد، لأن الملفات الطويلة تستهلك السياق وتضعف الالتزام.

الطبقة الثانية: موجز المهمة

ملف التعليمات يصف المشروع كله. أما كل ميزة جديدة فتحتاج موجزًا خاصًا بها. في بناء ميزات هذا الموقع، بدأت كل ميزة بملف موجز يُسلَّم لوكيل البرمجة، وعبر تلك الملفات يتكرر هيكل من سبعة أقسام يمكنك نسخه:

1. السياق: أين يعمل الوكيل، وما التقنية المستخدمة، مع جمل صريحة مثل «لا تنشر» و«لا تلمس ملفات الأسرار».
2. ممنوع اللمس: قائمة بالأجزاء المعتمدة التي لا تتغير، مع الألوان والخطوط.
3. الهدف والمنتج: ما الذي يراه المستخدم، خطوة بخطوة.
4. قواعد البيانات والسلامة: ما الذي لا يجوز اختلاقه، وما الذي لا يُخزَّن، وما الحدود.
5. الاختبارات: ما الذي يجب التحقق منه، مع منع الاتصال بالشبكة الحقيقية داخل الاختبارات.
6. التجربة المحلية: خطوات تشغيل يدوية ينفذها الوكيل قبل أن يعلن الانتهاء.
7. معايير الانتهاء: قائمة قصيرة، إذا تحققت كلها اكتملت المهمة.

القسم السابع يحوّل كلمة «انتهيت» من انطباع إلى قائمة يمكن التحقق منها. والقسم الثاني يحمي ما اعتمدته سابقًا من تعديلات جانبية لم تطلبها.

أخطاء شائعة تتجنبها

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

الخطوات باختصار

1. أنشئ AGENTS.md في جذر المشروع بأوامر التشغيل والاختبار وقواعدك الأساسية.
2. إن كنت تستخدم Claude Code ومعه ملف CLAUDE.md، أضف إليه سطر الاستيراد.
3. لكل ميزة، اكتب موجزًا بالأقسام السبعة.
4. اطلب من الوكيل تشغيل الاختبارات والتجربة المحلية قبل أن يعلن الانتهاء.
5. راجع النتيجة بنفسك قبل أي نشر.

المصادر

• الموقع الرسمي لصيغة ملف تعليمات الوكلاء
• توثيق Codex لملفات التعليمات
• توثيق Claude Code لملفات التعليمات والذاكرة
• دليل Next.js لإعداد المشروع لوكلاء البرمجة

مصدر صورة الغلاف: الصورة الرسمية لموقع AGENTS.md.

---

عبدالرحمن الشهري — أبني ما هو قادم.