كيف تكتب ملف AGENTS.md يساعد فعلاً وكيل البرمجة بالذكاء الاصطناعي لديك

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

ما هو AGENTS.md

AGENTS.md هو تنسيق Markdown بسيط ومفتوح يمنح وكلاء البرمجة مكاناً متوقَّعاً للعثور على سياق المشروع وتعليماته. بدأ كتعاون بين OpenAI Codex وAmp وGoogle Jules وCursor وFactory، وترعاه الآن Agentic AI Foundation تحت Linux Foundation. تقرأه أكثر من 25 أداة — بما في ذلك Codex وCursor وVS Code وGitHub Copilot وAider وWindsurf وJetBrains Junie وZed وgoose — ويظهر في أكثر من 60,000 مستودع مفتوح المصدر.

فكّر فيه كملف README مكتوب للوكيل بدلاً من إنسان: README يشرح مشروعك لمساهم جديد؛ بينما AGENTS.md يخبر الوكيل بالأشياء التي كان سيخمّنها خطأً لولاه. (سيتعرّف مستخدمو Claude Code على CLAUDE.md كمكافئ؛ تحتفظ فرق كثيرة بكليهما، أو تربط أحدهما رمزياً (symlink) بالآخر.)

أين يوضع

ضع AGENTS.md في جذر المستودع. في monorepo، أضف ملفات متداخلة داخل كل حزمة — يقرأ الوكلاء أقرب ملف في شجرة الأدلة، فيتقدّم packages/api/AGENTS.md على ملف الجذر عندما يعمل الوكيل في ذلك المجلد. هذا يتيح لخدمة Python وواجهة TypeScript الأمامية أن يحصل كلٌّ منهما على تعليمات مخصّصة.

ماذا تضع فيه

التنسيق هو مجرد Markdown — استخدم أي عناوين تحب. تشمل الأقسام المفيدة شائعاً:

• أوامر البناء والاختبار — الأوامر الدقيقة، لا التقريبات
• أسلوب الكود — المنسّق، والمدقق اللغوي، وأي أعراف لن يلتقطها مدقق لغوي
• تعليمات الاختبار — كيفية تشغيل اختبار واحد، وما الذي يجب أن ينجح قبل اكتمال تغيير
• اعتبارات أمنية — ملفات أو عمليات لا تُلمس أبداً
• أعراف الـ commit / PR — تنسيق الرسائل، تسمية الفروع
• خطوات النشر — فقط إذا كان من المتوقّع أن يلمسها الوكيل

إليك مثالاً بسيطاً عالي الإشارة:

# AGENTS.md

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (do NOT run in CI)
- Test a single file: `pnpm vitest run path/to/file.test.ts`
- Lint + typecheck before any commit: `pnpm check`

## Conventions
- Use the existing `db()` helper in `src/lib/db.ts`; never open a raw client.
- Dates are stored as UTC ISO strings. Never use `Date.now()` in tests.

## Do not touch
- `src/generated/**` is codegen output. Edit the schema, then run `pnpm gen`.

لاحظ ما هو غير موجود: لا محاضرة معمارية، ولا إعادة سرد لبنية المجلدات، ولا "هذا تطبيق ويب حديث مبني بأفضل الممارسات." هذا متعمَّد.

الأقصر عادةً أفضل

هناك إغراء بأن تطلب من الوكيل توليد ملف AGENTS.md ضخم لك. قاوِمه. قاست دراسة من ETH Zurich عام 2026، أوردها InfoQ، الأثر الحقيقي لهذه الملفات ووجدت أن التأثير هامشي ومختلط. ملفات السياق المولَّدة بنموذج لغوي خفّضت فعلياً معدلات نجاح المهام بنحو 3% في المتوسط بينما رفعت تكاليف الاستدلال بأكثر من 20%. الملفات المكتوبة بشرياً ساعدت بشكل متواضع — مكسب نحو 4% في النجاح — لكنها مع ذلك دفعت الوكلاء لاتخاذ خطوات أكثر، مما رفع التكلفة بنسبة تصل إلى نحو 19%.

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

بعبارة أخرى، ينبغي أن يكسب كل سطر مكانه بمنع خطأ ملموس رأيت الوكيل يرتكبه فعلاً.

سير عمل يعمل

1. ابدأ فارغاً. لا تكتب AGENTS.md حتى تشاهد الوكيل يخطئ في شيء.
2. أضف الإصلاح، لا النظرية. عندما يشغّل أمر الاختبار الخاطئ، أضف الصحيح. عندما يعيد تنسيق ملف بطريقتك ويشتكي المدقق اللغوي، أضف القاعدة.
3. أبقِه محكماً. إذا كان سطر يعيد فقط سرد ما يستطيع الوكيل قراءته من package.json أو أسماء المجلدات، احذفه.
4. استخدم التداخل لـ monorepos حتى يبقى ملف كل حزمة صغيراً.
5. أعد قراءته شهرياً. التعليمات القديمة أسوأ من لا شيء — وكيل يتبع أمر بناء عفا عليه الزمن يفشل بثقة.

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