ما مكانه في الملف
الحقائق التي لا يستطيع الوكيل استنتاجها من قراءة المستودع: أي مدير حزم، وأمر الاختبار بالضبط، وأي المجلدات مولَّدة، وأي واجهة لا يجوز تغيير شكلها. وكل ما عدا ذلك يراه بنفسه.
مولّد AGENTS.md
الملف الذي يقرؤه وكيل البرمجة حين يفتح مستودعك. أجب عمّا لا يستطيع استنتاجه وحده، كمدير الحزم وأمر الاختبارات وما يجب ألّا يلمسه، ثم خذ الملف بالصيغة التي تتوقّعها أداتك.
- الصيغ4 صيغ من مجموعة إجابات واحدة
- القوالب الجاهزة4 بيئات تقنية
- يقرؤه الوكيلفي كل جلسة
ما لا يستطيع الوكيل تخمينه
كل ما تكتبه هنا يصل إلى الملف. اترك الحقل فارغاً ليُحذف سطره.
المشروع
البيئة التقنية
الأوامر
السطر الذي تكتبه بالضبط، لا وصفاً له.
القواعد
القاعدة التي تستحق الكتابة هي التي سبق أن أخطأ فيها أحد.
الملف
احفظه باسم AGENTS.md (في جذر المستودع). تقرؤه معظم وكلاء البرمجة، ومنها Claude Code وCursor. ابدأ بكتابته أولاً.
52 سطر · 1,409 حرف · ≈ 376 توكن في كل جلسة
ما يجب حذفه
«اكتب شيفرة نظيفة»، «اتّبع أفضل الممارسات»، «استخدم أسماء ذات معنى». هذه العبارات تستهلك السياق ولا تغيّر شيئاً، فلا يوجد وكيل كان ينوي كتابة شيفرة سيئة عمداً. القاعدة التي تستحق الكتابة هي التي سبق أن أخطأ فيها أحد.
أبقِه قصيراً
يُقرأ هذا الملف في كل جلسة، فتدفع ثمن كل سطر فيه مراراً، وعدد التوكنات أسفل الملف هو هذه التكلفة المتكرّرة. مئتا سطر مفيد أفضل من ألف سطر متحفّظ، والقاعدة التي لم تعد صحيحة تُحذف بدل أن تبقى مضلِّلة.
الأسئلة الشائعة
- ما هو ملف AGENTS.md؟
- هو ملف Markdown في جذر المستودع يخبر وكيل البرمجة كيف يعمل داخله: أي مدير حزم يستخدم، وأمر الاختبارات بالضبط، وأي المجلدات مولَّدة، وما الذي يجب ألّا يلمسه. يقرأه الوكيل في بداية الجلسة كما يقرأ زميل جديد دليل المساهمة.
- ماذا أكتب في ملف AGENTS.md؟
- فقط ما لا يستطيع الوكيل استنتاجه من الشيفرة: مدير الحزم، وأمر الاختبارات الحقيقي، والمجلدات المولَّدة التي ستُكتب فوقها، والواجهة التي لا يجوز تغيير شكلها. كل ما عدا ذلك يراه بنفسه.
- ما الذي يجب ألّا أكتبه فيه؟
- التعليمات العامة مثل «اكتب شيفرة نظيفة» أو «اتّبع أفضل الممارسات». تكلّف توكنات في كل جلسة ولا تغيّر شيئاً. القاعدة التي تستحق الكتابة هي التي تصف خطأً وقع فعلاً.
- هل AGENTS.md هو نفسه CLAUDE.md أو .cursorrules؟
- المحتوى متقارب إلى حد بعيد، والاختلاف في اسم الملف وبعض الأعراف الخاصة بكل أداة. اختر الصيغة التي تتوقّعها أداتك من أعلى الصفحة وسيُخرج المولّد الملف وفقها، فتنتج الإجابات نفسها أيّاً من الصيغ الأربع تحتاج.