وكلاء البرمجة يقرأون مستودعك قبل أن يكتبوا التعليمات البرمجية، والملف الذي يقرأونه أولاً هو AGENTS.md. إنها الاتفاقية المفتوحة التي وافقت عليها Codex CLI، وCursor، وAider، وOpenHands، وقائمة متزايدة من الأدوات الأخرى بحيث يعمل ملف سياق واحد عبر كل وكيل. بالنسبة لفرق تطوير واجهة برمجة التطبيقات (API)، هذا الملف هو الفرق بين وكيل يقوم بتشغيل الاختبارات الصحيحة مقابل خادم محلي حقيقي ووكيل يهذي بنقاط النهاية ويشحن عميلاً معطوبًا.
يغطي هذا الدليل ما هو AGENTS.md، ولماذا يجب على فرق واجهة برمجة التطبيقات التعامل معه كرمز إنتاجي، والأقسام المهمة لمستودعات OpenAPI-first، والأمثلة العملية، وكيفية تحديثه مع تطور واجهة برمجة التطبيقات. نقوم بإقرانه بـ Apidog في النهاية بحيث يظل سير عمل اختبار العقود للوكيل متجذرًا في مواصفات حقيقية.
ملخص
AGENTS.mdهو ملف Markdown عادي في جذر المستودع يخبر وكلاء البرمجة كيفية التنقل والبناء والاختبار وشحن التعليمات البرمجية في مشروعك.- الاتفاقية مفتوحة ومدعومة عبر Codex CLI وCursor وOpenHands وAider وClaude Code وأدوات الوكلاء الأخرى.
- بالنسبة لفرق واجهة برمجة التطبيقات، فإن الأقسام الأكثر فائدة هي أوامر البناء، ومسار مواصفات OpenAPI، ونقاط نهاية الخادم الوهمي، وأوامر اختبار العقود، وإعداد المصادقة، ومناطق "ممنوع اللمس".
- اجعله قصيرًا. 200 إلى 400 سطر كافية. أي شيء أطول وسيتخطى الوكيل الأجزاء المهمة.
- اقرنه بمجموعة Apidog بحيث يمتلك الوكيل كلاً من السياق (
AGENTS.md) وعقدًا قابلاً للتشغيل (مواصفات OpenAPI).
ما هو AGENTS.md بالفعل
AGENTS.md هو ملف Markdown تقوم بتثبيته في جذر المستودع. يبحث وكلاء البرمجة عنه عند أول اتصال بقاعدة التعليمات البرمجية ويعاملون محتوياته على أنها الإحاطة الرسمية حول كيفية عمل المشروع. بدأت الاتفاقية داخل Codex CLI من OpenAI وتم نشرها كمعيار مفتوح حتى تتمكن الأدوات الأخرى من قراءة نفس الملف. اعتبارًا من هذا العام، تقرأه Codex CLI، وCursor، وAider، وClaude Code، وOpenHands، وSourcegraph Cody، والعديد من الوكلاء الأصغر حجمًا.
ثلاثة أشياء تجعله مفيدًا:
- ملف واحد، كل وكيل. تكتب السياق مرة واحدة ويلتقطه كل وكيل في مجموعة أدوات الفريق. لا يوجد انحراف في تكوين كل أداة.
- Markdown عادي. لا توجد لغة وصف نطاقية، لا مخطط، لا خطوة بناء. يقوم المهندسون بتحريره مثل أي مستند آخر.
- يعيش بجوار التعليمات البرمجية التي يصفها. عندما يتغير نص البناء، يتغير الملف في نفس طلب السحب (PR). يوضح الاختلاف التغيير للمراجعين وللوكيل.
أقرب ملف مشابه هو CLAUDE.md، الذي يقرأه Claude Code من Anthropic. تتداخل التنسيقات بشكل كبير؛ تحتفظ العديد من المشاريع بملف AGENTS.md مرتبط رمزيًا بـ CLAUDE.md بحيث تعمل كلتا الأداتين دون تكوين إضافي. وقد اتفقت فرق Codex وAnthropic علنًا على الحفاظ على توافق التنسيقات في المستقبل.
لماذا تحتاج فرق تطوير واجهة برمجة التطبيقات إليه أكثر من معظم الفرق الأخرى
تجلس فرق واجهة برمجة التطبيقات في تقاطع محرج: التعليمات البرمجية صغيرة، والعقود كبيرة، وتظهر عواقب الخطأ في أي منهما لكل عميل تابع. الوكيل الذي لا يعرف أن المواصفات موجودة في openapi.yaml سيعيد كتابة الأنواع من شكل الاستجابة الذي يتذكره من بيانات التدريب. الوكيل الذي لا يعرف أمر اختبار العقد سيلتزم برمز يتم تجميعه ولكنه يكسر مسار SDK للعميل.
ملف AGENTS.md مكتوب بشكل جيد لمستودع واجهة برمجة التطبيقات يقوم بأربعة أشياء:
- يثبت المواصفات كمصدر للحقيقة. كل تغيير يبدأ وينتهي بمخطط OpenAPI أو GraphQL. يتعلم الوكيل تحديث المواصفات أولاً، ثم إعادة إنشاء الأنواع.
- يسمي الخوادم المحلية. تختار الوكلاء الذين يقومون بتشغيل خادم وهمي محلي أو خادم مباشر عنوان URL الصحيح للاختبارات، وليس مقتطفًا من Stack Overflow.
- يسرد أوامر الاختبار حسب الغرض. "تشغيل اختبارات الوحدة" ليس هو نفسه "تشغيل اختبارات العقود" أو "تشغيل اختبارات التكامل ضد بيئة الاختبار المرحلي".
- يحدد المسارات المحظورة. غالبًا ما تبدو التعليمات البرمجية لـ SDK التي تم إنشاؤها، ومغلفات العملاء الخارجية، وملفات الترحيل قابلة للتحرير ولكنها ليست كذلك.
عندما يقوم الملف بهذه الأشياء الأربعة، يتوقف مخرجات الوكيل عن أن تبدو وكأنها مبرمج مبتدئ تخطى ملف README ويبدأ في الظهور كزميل في الفريق.
الهيكل الذي يعمل لمستودعات واجهة برمجة التطبيقات
لا يحتوي AGENTS.md على مخطط مطلوب. استقرت المجتمع على بضعة أقسام تظهر في كل ملف جيد الضبط تقريبًا. بالنسبة لفريق واجهة برمجة التطبيقات، الترتيب أدناه هو افتراضي قوي.
1. ملخص المشروع (3-5 أسطر)
اذكر ما تفعله واجهة برمجة التطبيقات، ومن هم المستهلكون، واللغة والإطار الذي يعمل عليه الخادم. اجعلها حقائق.
# المشروع: Payments API
خدمة المدفوعات الداخلية لخط منتجات Acme. العملاء هم
الجوّال، والويب، والخوادم الخلفية الشريكة. الخادم هو Go 1.23 على Echo، Postgres
17 للتخزين، وطبقة استقلالية مدعومة بـ Redis.
تخبر هذه الكتلة الوكيل باللغة التي يجب استخدامها افتراضيًا، والأساليب التي يجب اتباعها، والعملاء الذين سيتعطلون إذا قمت بشحن شكل استجابة خاطئ.
2. أوامر البدء السريع
من خمسة إلى عشرة أوامر سيشغلها الوكيل باستمرار. قم دائمًا بتضمين الأمر، ولا ترتبط أبدًا بويكي.
## الأوامر
| الغرض | الأمر |
|--------|---------|
| تثبيت التبعيات | `make deps` |
| تشغيل الخادم محليًا | `make dev` (يرتبط بـ 127.0.0.1:8080) |
| تشغيل اختبارات الوحدة | `make test` |
| تشغيل اختبارات العقود مقابل الخادم الوهمي المحلي | `make contract` |
| التحقق من الأنماط | `make lint` |
| إعادة إنشاء العملاء من المواصفات | `make codegen` |
| تطبيق الترحيلات | `make migrate` |
إذا كان الأمر يحتاج إلى متغير بيئة للعمل، ضع اسم متغير البيئة بجانبه. الوكلاء جيدون في تصدير المتغيرات؛ وهم سيئون في التخمين.
3. قسم مواصفات OpenAPI / GraphQL
هذا هو القسم الأكثر قيمة في مستودع واجهة برمجة التطبيقات. أخبر الوكيل بمكان وجود المواصفات، وكيف ترتبط المواصفات بالتعليمات البرمجية التي تم إنشاؤها، والاتجاه الذي تتدفق فيه التعديلات.
## مصدر الحقيقة
- المواصفات موجودة في `apis/payments/openapi.yaml`.
- تعيش العملاء التي تم إنشاؤها في `gen/clients/{go,ts,python}` ويجب عدم تحريرها يدويًا.
- خط أنابيب الإنشاء هو `make codegen`. قم بتشغيله بعد كل تغيير في المواصفات
وقم بتثبيت العملاء الذين تم إنشاؤهم في نفس طلب السحب (PR).
- تدفق تغييرات المواصفات: المواصفات -> `make codegen` -> تحديثات معالج الخادم ->
اختبارات العقود -> الشحن.
هذه الكتلة وحدها تزيل فئة من الأخطاء حيث يقوم الوكلاء بتحرير العميل الذي تم إنشاؤه "لإصلاح" عدم تطابق في النوع، ثم يقوم تشغيل `codegen` التالي بمسح التغيير، ثم يتعطل البناء بشكل غامض بعد يومين.
4. الخادم الوهمي وتوصيل Apidog
إذا كنت تشغل خوادم وهمية (ويجب عليك)، فقم بتسميتها. اذكر عناوين URL، والمواصفات التي يقرأونها منها، وكيفية بدء تشغيلها.
## الخوادم المحلية
- الخادم الحقيقي: `make dev` -> `http://127.0.0.1:8080`
- خادم Apidog الوهمي: `make mock` -> `http://127.0.0.1:4010`
- يقرأ الخادم الوهمي من نفس `openapi.yaml` ويعيد تشغيل الأمثلة المحفوظة
من مجموعة Apidog في `apis/payments/apidog/`.
هذا هو المكان الذي تكسب فيه Apidog مكانتها في الملف. يشكل الخادم الوهمي والمواصفات وأمثلة الطلبات المحفوظة عقدًا يمكن للوكيل تشغيله دون حرق المكالمات على الواجهة الخلفية الحقيقية. قم بإقرانه مع دليل اختبار واجهة برمجة التطبيقات بدون Postman لسير العمل الأساسي.
5. المصادقة والأسرار
أخبر الوكيل كيف تقوم واجهة برمجة التطبيقات بالمصادقة وما هي متغيرات البيئة التي تحتوي على ماذا. لا تضع أبدًا أسرارًا حقيقية في الملف.
## المصادقة
- يستخدم الإنتاج بيانات اعتماد عميل OAuth 2 الصادرة عن Auth0.
- يستخدم التطوير المحلي رمزًا ثابتًا للتطوير؛ قم بتصدير `DEV_TOKEN` من `.env.local`.
- تستخدم مجموعة Apidog نفس أسماء متغيرات البيئة بحيث يتصرف الوكيل الوهمي و
العميل الحقيقي بشكل متطابق.
- يجب عدم الالتزام بالرموز المميزة؛ `.env.local` موجود في `.gitignore`.
6. استراتيجية الاختبار
رتب طبقات الاختبار. سيقوم الوكلاء بتشغيلها بالترتيب الذي تسردونه.
## الاختبار
1. `make test` لاختبارات الوحدة. سريعة، تعمل مع كل تغيير.
2. `make contract` لاختبارات عقود OpenAPI مقابل الخادم الوهمي. تُشغل قبل
دمج أي تغيير في المواصفات.
3. `make integration` لاختبارات شاملة ضد خادم محلي مع قاعدة بيانات Postgres حقيقية. تُشغل قبل الدمج في الفرع الرئيسي.
4. اختبار التحمل على بيئة الاختبار المرحلي (staging soak) يُشغل ليليًا عبر GitHub Actions؛ ليس أمرًا محليًا.
7. قائمة "ممنوع اللمس"
دائمًا ما تنتمي التعليمات البرمجية المولدة والتبعيات الموردة والترحيلات إلى هنا.
## لا تقم بالتحرير يدويًا
- `gen/**` (يعاد إنشاؤه بواسطة `make codegen`)
- `vendor/**` (يتم إدارته بواسطة `go mod vendor`)
- `migrations/*.up.sql` بعد الترحيل الأول غير المطبق
- `apis/payments/openapi.yaml` أسماء حقول المخطط بدون موافقة المالك
8. نمط المنزل
من ثلاث إلى خمس قواعد. أي شيء أكثر وسيختار الوكيل القاعدة الخاطئة.
## الاتفاقيات
- تعيد الأخطاء JSON لمشكلة RFC 7807؛ لا سلاسل نصية مجردة أبدًا.
- استخدم `snake_case` في JSON، و`camelCase` في Go، و`PascalCase` في عملاء TS.
يتعامل Codegen مع التعيين.
- مفاتيح الاستقلالية مطلوبة في جميع نقاط نهاية POST التي تنشئ موارد.
- تتطلب نقاط النهاية الجديدة اختبار عقد يختبر كلا المسارين 200 و 4xx.
مثال عملي: ملف من 90 سطرًا يفي بالغرض
الإغراء هو كتابة 800 سطر. قاومه. الملف أدناه يغطي خدمة واجهة برمجة تطبيقات حقيقية في 90 سطرًا من Markdown وهو كافٍ لأي وكيل رئيسي للعمل بشكل منتج.
# المشروع: Payments API
خدمة المدفوعات الداخلية لخط منتجات Acme. Go 1.23، Echo،
Postgres 17، Redis للاستقلالية. المستهلكون هم الجوال، الويب،
والخوادم الخلفية الشريكة.
## الأوامر
| الغرض | الأمر |
|--------|---------|
| تثبيت | `make deps` |
| تشغيل الخادم | `make dev` |
| اختبارات الوحدة | `make test` |
| اختبارات العقود | `make contract` |
| التحقق من الأنماط | `make lint` |
| إعادة إنشاء العملاء | `make codegen` |
| ترحيل قاعدة البيانات | `make migrate` |
## مصدر الحقيقة
- المواصفات: `apis/payments/openapi.yaml`
- العملاء المولّدون: `gen/clients/{go,ts,python}` (لا تعدّل)
- تدفق التعديل: مواصفات -> `make codegen` -> معالج -> اختبارات العقود -> شحن
## الخوادم المحلية
- خادم حقيقي: `make dev` (`http://127.0.0.1:8080`)
- Apidog وهمي: `make mock` (`http://127.0.0.1:4010`)
- مجموعة Apidog: `apis/payments/apidog/`
## المصادقة
- الإنتاج: بيانات اعتماد عميل Auth0 OAuth 2.
- التطوير المحلي: `DEV_TOKEN` ثابت من `.env.local`.
## ترتيب الاختبار
1. `make test`
2. `make contract`
3. `make integration`
## لا تعدّل يدويًا
- `gen/**`، `vendor/**`
- الترحيلات المطبقة في `migrations/`
- أسماء حقول المواصفات بدون موافقة المالك
## الاتفاقيات
- JSON لمشكلة RFC 7807 للأخطاء
- `snake_case` JSON، `codegen` يتعامل مع تعيين اللغة
- مفاتيح الاستقلالية مطلوبة في POSTs التي تنشئ موارد
- كل نقطة نهاية جديدة تُشحن باختبار عقد
هذا يكفي. أضف أقسامًا فقط عندما يرتكب الوكيل نفس الخطأ مرتين.
الحفاظ على الملف حديثًا
ملف AGENTS.md قديم أسوأ من عدم وجود ملف على الإطلاق. سيعتقد الوكيل أنه صحيح ويقوم بشحن تعليمات برمجية بناءً على أمر بناء لم يعد يعمل.
ثلاث عادات تحافظ عليه حديثًا:
- عامله كرمز إنتاجي. التغييرات تمر بنفس المراجعة مثل أي طلب سحب آخر. يتحقق المراجعون من تطابق قوائم الأوامر مع ملف
Makefileالفعلي. - اربطه بالاندماج المستمر (CI). نص برمجي قصير يحلل جدول الأوامر ويشغل كل أمر على نسخة جديدة من المستودع يكتشف الانحراف بسرعة. تكتب معظم الفرق هذا في 30 سطرًا من Bash.
- حدثه في نفس طلب السحب. عندما تضيف أمر اختبار جديد، لا تعد بتحديث
AGENTS.mdلاحقًا. حدثه الآن. التكلفة دقيقتان؛ تكلفة التخطي هي أسبوعان من ارتباك الوكيل.
Apidog كعقد وقت التشغيل لـ AGENTS.md الخاص بك
يمنح AGENTS.md الوكيل السياق. تمنحه مواصفات OpenAPI العقد. Apidog يربط بين الاثنين: يقرأ المواصفات، يشغل خادمًا وهميًا محليًا على عنوان URL المدرج في AGENTS.md، يعيد تشغيل أمثلة الطلبات المحفوظة للاختبارات، ويسمح للوكيل برؤية استجابات حقيقية دون حرق الرصيد على الواجهة الخلفية الحية.
النمط الذي يعمل:
- قم بتثبيت
apis/<service>/openapi.yamlوapis/<service>/apidog/(المجموعة المصدرة). - اسرد عنوان URL الوهمي وأمر
make mockفيAGENTS.md. - يشغل الوكلاء
make contractلاختبارات سريعة مقابل الأمثلة المحفوظة. - عندما تتغير المواصفات، يعيد الوكيل إنشاء العملاء، ويشغل مجموعة العقود، وعندها فقط يلمس الخادم الحي.
للحصول على شرح أعمق لسير عمل Apidog الوهمي مع واجهة برمجة تطبيقات حقيقية، يغطي دليل DeepSeek V4 API نفس النمط المطبق على واجهة برمجة تطبيقات نموذجية بدلاً من واجهة برمجة تطبيقات خدمية.
أخطاء شائعة ترتكبها فرق واجهة برمجة التطبيقات
بعد مراجعة العشرات من هذه الملفات، تظهر نفس المشكلات الخمس:
- الربط بدلاً من الإدراج. "راجع الويكي لأوامر البناء." الوكيل لا يتصفح الويكي. ادرج الأوامر مباشرة.
- نثر بأسلوب تسويقي. "منصة واجهة برمجة التطبيقات عالمية المستوى تمكّن..." الوكيل لا يحتاج إلى عرض تسويقي. اذكر الحقائق.
- أوامر قديمة. أمر تعطل في مارس لا يزال موجودًا في الملف في أبريل. اربط CI لاكتشاف ذلك.
- نقص قسم المواصفات. الكتلة الأكثر فائدة على الإطلاق. قم بتضمينها دائمًا.
- لا توجد قائمة "ممنوع اللمس". يقوم الوكيل بتحرير التعليمات البرمجية المولدة. يقوم تشغيل `codegen` التالي بمسح التعديل. يتعطل البناء. تكرار.
إذا كنت تريد نقطة بداية، انسخ المثال أعلاه في مستودعك، وقم بتحرير ملخص المشروع، واضبط جدول الأوامر. يمكنك شحن ملف قابل للاستخدام في 20 دقيقة.
الأسئلة الشائعة
هل AGENTS.md هو نفسه CLAUDE.md؟التنسيقات متوافقة. تحتفظ معظم الفرق بأحدهما كمصدر للحقيقة وتربط الآخر رمزيًا. وقد اتفقت Anthropic وOpenAI علنًا على الحفاظ على توافق الاصطلاحات.
أين يجب أن أضع الملف؟دائمًا في جذر المستودع. تقرأ بعض الوكلاء أيضًا ملفات AGENTS.md المتداخلة داخل الدلائل الفرعية، وهو مفيد للمستودعات الكبيرة (monorepos). ابدأ بملف واحد على مستوى الجذر وأضف ملفات الدلائل الفرعية فقط عندما يصبح ملف الجذر الواحد طويلًا جدًا.
كم يجب أن يكون طوله؟من 200 إلى 400 سطر هو النقطة المثالية. بعد ذلك، تبدأ الوكلاء في تخطي الأقسام. إذا كنت بحاجة إلى مزيد من التفاصيل، اربط بمستند منفصل مع ملخص من سطر واحد مباشرة.
هل يجب أن أضمّن عينات التعليمات البرمجية؟عينات قصيرة، نعم. عينات طويلة، لا. احفظ الأمثلة الكاملة للاختبارات؛ تقرأ الوكلاء الاختبارات أيضًا. يغطي دليل GPT-5.5 free Codex كيف يستخدم Codex على وجه التحديد اختبارات الأمثلة كإشارة إضافية.
هل يعيد الوكيل قراءة الملف في كل منعطف؟تقرأ معظم الوكلاء الملف عند بدء الجلسة وتخزنه مؤقتًا. يعيد بعضها القراءة بعد التغييرات الكبيرة في الملف. إذا قمت بإجراء تعديل كبير، فإن إعادة تشغيل جلسة الوكيل هي الخطوة الأكثر أمانًا.
كيف أختبر أن ملفي يعمل؟قم بتشغيل جلسة وكيل جديدة بدون سياق آخر، وامنحه مهمة صغيرة ("أضف استجابة 422 إلى POST /payments")، وشاهد ما يفعله. إذا قرأ المواصفات، وشغل make codegen، وكتب اختبار عقد، فإن الملف يقوم بعمله.