ملف AGENTS.md ليس دليلاً ثانياً لتشغيل التطبيق، وليس prompt يحاول التحكم في كل ضغطة. إنه عقد صغير للسياق محفوظ مع نسخ المشروع. يوضح لوكيل البرمجة كيف بُني المستودع، وما الأوامر التي تعطي أدلة قابلة للتحقق، وما الحدود المهمة، وأين توجد القاعدة الأكثر تخصصاً. يقلل الملف الجيد عدم اليقين قبل أن يغير الوكيل الكود. ولا يحل محل الكود المصدر أو الاختبارات أو مسؤولي المشروع أو وصف المهمة.
للسياق كلفة. يحمّل Codex إرشادات المشروع ضمن سلسلة التعليمات قبل بدء العمل. ينافس النص المكرر طلب المستخدم وملفات المستودع ونتائج الأدوات والاختبارات. لذلك اكتب الحقائق التي لا يستطيع الوكيل استنتاجها بأمان، لا كل تفضيل عبّر عنه شخص في الماضي. تعامل مع كل جملة بوصفها واجهة تحتاج إلى صيانة.
ما الذي يكتشفه Codex فعلياً
يشرح دليل OpenAI الحالي عن AGENTS.md في Codex ثلاث طبقات. في النطاق العام، يبحث Codex عن AGENTS.override.md داخل CODEX_HOME، وقيمته الافتراضية ~/.codex، ثم يستخدم AGENTS.md عند عدم وجوده. يستخدم أول ملف غير فارغ فقط في هذا المستوى. في نطاق المشروع، يبدأ من جذر المشروع، وهو عادة جذر Git، ثم ينزل حتى دليل العمل الحالي. وفي كل دليل يبحث بالترتيب عن AGENTS.override.md ثم AGENTS.md ثم أسماء بديلة مهيأة، ويضم ملفاً واحداً كحد أقصى من كل دليل.
تُجمع ملفات المشروع من الجذر إلى الدليل الحالي. يظهر الملف الأعمق لاحقاً في التعليمات المدمجة، ولذلك يمكن لقاعدته الأضيق أن تتغلب على القاعدة العامة. لا يواصل Codex البحث خارج جذر المشروع المكتشف. وإذا لم يجد جذراً، يفحص الدليل الحالي فقط. يتجاهل الملفات الفارغة. قيمة project_doc_max_bytes الافتراضية هي 32 KiB، ويتوقف Codex عن إضافة الإرشادات عند الوصول إلى الحد الإجمالي المهيأ. هذه خصائص Codex، وليست وعداً عاماً من كل أداة.
توضح شيفرة اكتشاف AGENTS.md في مستودع OpenAI Codex الحدود نفسها. علامة الجذر الافتراضية هي .git، والاسم المحلي المفضل هو AGENTS.override.md، وقد يُقتطع الملف إذا كان حجم الميزانية المتبقية بالبايت أصغر من محتواه. يستطيع المستودع ضبط علامات الجذر والأسماء البديلة والميزانية. وثّق الإعدادات التي تستخدمها فعلاً فقط.
تنتمي التفضيلات العامة إلى ~/.codex/AGENTS.md فقط إذا كانت آمنة في كل مستودع. ضع قاعدة المستودع كله في الجذر. ضع قاعدة الخدمة بجوار الخدمة. وضع الاستبدال المؤقت أو الاستثنائي في ملف override مع مالك وشرط إزالة. لا تقدم ذلك على أنه تسلسل عام لكل الوكلاء إذا لم تؤكده وثائق الأدوات الأخرى.
ابدأ بخريطة للمستودع
يحتاج الوكيل إلى نقطة توجه قبل حاجته إلى نصائح الأسلوب. ضع خريطة موجزة قرب بداية الملف الجذري. سمِّ التطبيق أو المكتبة، وأدلة المصدر الأساسية، والمناطق المولدة، وأدلة الاختبار، وإعداد النشر. اشرح الفروق التي تغير الفعل فقط. قولك إن «src/ يحتوي على الكود» ضعيف. قولك إن «src/ يُشحن، و scripts/ يعمل في CI فقط، وdist/ مولد ولا يجوز تعديله يدوياً» مفيد.
يجب أن تصمد الخريطة أمام إعادة الهيكلة العادية. فضّل الحدود المستقرة على قائمة بكل ملف. في المستودع المتعدد الحزم، أظهر مالك كل حزمة وضع الخرائط الخاصة في ملفات متداخلة. اربط بملف README أو وثيقة العمارة التي تمثل مصدر الحقيقة. لا تنسخ تلك الوثيقة داخل AGENTS.md.
repository/
apps/web/ تطبيق المتصفح واختبارات المسارات
packages/core/ مكتبة التشغيل المشتركة واختبارات الوحدة
services/api/ معالجات HTTP واختبارات العقد
infra/ إعداد النشر
docs/ شروحات مصانة
generated/ ناتج محفوظ يعاد توليده بواسطة script
اكتب افتراضات دليل العمل بوضوح. قد يجد الأمر الذي يعمل من services/api ملف تعليمات متداخلاً مختلفاً عن الأمر نفسه من الجذر. إذا كان يجب تشغيل مدير الحزم من دليل الحزمة، اذكر ذلك. وإذا كان للملف المولد مصدر حقيقة، فاذكر المسارين وأمر التوليد.
اجعل الأوامر دقيقة ومشروطة
يكون الأمر مفيداً عندما يمكن نسخه دون تفسير. لكل أمر مطلوب، اذكر الدليل والغرض وشرط التشغيل. استخدم الإصدارات والبرامج النصية التي يعلنها المستودع، لا أداة شائعة تتذكرها. يمكن أن يبدو قسم الأوامر هكذا:
من جذر المستودع:
git rev-parse --show-toplevel
npm ci
npm run check
npm test
npm run build
لتغييرات API، شغّل من services/api:
npm run test:contract
هذه بنية مثال، وليست ادعاءً بوجود هذه البرامج النصية في كل مشروع. اقرأ package.json وlockfile وملفات CI وpyproject.toml وCargo.toml أو ما يعادلها قبل كتابتها. لا تقل «شغّل npm run check بعد تغيير TypeScript» إلا إذا كان البرنامج النصي موجوداً. إذا احتاج الأمر إلى خدمة محلية أو fixture أو قاعدة بيانات أو متغير بيئة أو شبكة، فاذكر المتطلب والبديل الآمن للاختبار المركز.
سجل بيئة التشغيل المدعومة وسياسة الاعتماديات. يجب أن يذكر الإدخال إصدار Node أو Python أو Rust أو Java أو Go، ومدير الحزم، وسياسة lockfile، وطريقة مراجعة تحديثات الاعتماديات. مثلاً، «يعلن package.json عن Node >=22.12.0، استخدم package-lock.json المحفوظ وشغّل npm ci» حقيقة إذا أكدها البيان. لا تنسخ إصداراً إلى AGENTS.md من دون فحص البيان وCI. اختلاف الإصدارات خلل صيانة، وليس سبباً لإضافة نص أكثر.
يمكن لـ Codex التحقق من السلسلة الفعالة. يعرض الدليل الرسمي أوامر مثل:
codex --ask-for-approval never "Summarize the current instructions."
codex --cd services/api --ask-for-approval never "List the instruction sources you loaded."
codex -c log_dir=./.codex-log --ask-for-approval never "Show the active instruction files."
استخدم طلباً غير تدميري وافحص السجل في مساحة عمل محلية آمنة فقط. أعد تشغيل run بعد تغيير ملفات التعليمات، لأن الاكتشاف يعاد بناؤه عند بداية run أو جلسة TUI. تشير الإجابة القديمة إلى ضرورة فحص دليل العمل وCODEX_HOME وملفات override والأسماء البديلة وحد البايتات.
الاختبارات أدلة وليست طقساً
صف معنى «تم» بنتائج يمكن ملاحظتها. افصل الفحوص السريعة عن المجموعة الكاملة. سمِّ أمر الاختبار والحزمة المتأثرة والملف الناتج المتوقع وطريق التصعيد عند الفشل. عند تغيير مخطط HTTP، اطلب اختبار العقد. وعند تغيير parser، اطلب fixtures ممثلة ومدخلات غير صالحة. وعند تغيير عميل مولد، اطلب إعادة التوليد وdiff نظيفاً.
لا تكتب «شغّل كل الاختبارات دائماً» إذا كان المستودع يحدد نطاقاً مختلفاً أو كانت المجموعة الكاملة تحتاج بنية خارجية. الأفضل قول «شغّل اختبار الحزمة المركز أولاً ثم مجموعة مساوية لـ CI قبل الدمج». اترك التنسيق وlint لـ CI إذا كانت تفرضهما هناك. مستودع SWE-bench مرجع أولي لتقييم المهام، لكنه لا يستبدل اختبارات المستودع نفسه.
اربط كل قاعدة مهمة بفحص. إذا كان ممنوعاً على الوكيل تعديل ناتج مولد، تستطيع CI إعادة تشغيل المولد والفشل عند ظهور diff. وإذا كان يجب أن تكون migration قابلة للعكس، يستطيع اختبار تطبيقها على fixture نظيفة ثم التراجع عنها. وإذا كان ثابت أمني مهماً، فاجعله اختباراً أو فحصاً ثابتاً. التعليمات التي لا تنتج نتيجة قابلة للملاحظة تطلب من الوكيل الاعتماد على الذاكرة.
لتقييم سلوك الوكيل، قارن نجاح المهمة ونسبة الاختبارات الناجحة ونطاق الملفات المعدلة وإعادة العمل بعد المراجعة والزمن حتى patch موثق. شغّل مجموعة المهام نفسها مع الملف القديم والجديد، وثبّت طلب المهمة وإصدار المستودع، وسجل الإخفاقات بدلاً من اختيار العروض الناجحة فقط. هذا مؤشر هندسي، وليس دليلاً على صلاحية صياغة واحدة لكل نموذج. راجع مقارنة الأدوات في agentic coding مع Codex وClaude Code، واقرأ عمارة AI agent في الإنتاج لحدود النظام وتقييم AI agents لتصميم الاختبار.
ضع الأمان عند الحدود
AGENTS.md مدخلات للمشروع. قد يكون قديماً أو خاطئاً أو غير موثوق. تتجنب شيفرة Codex صراحة تحميل تعليمات المشروع عندما لا يكون المشروع النشط موثوقاً، مع الإبقاء على التعليمات التي يرسلها المضيف. لا يلغي ذلك مراجعة الإنسان. تعامل مع تعليمات المستودع كنص غير موثوق حتى تتحقق من المستودع والتغيير المطلوب.
لا تضع مفاتيح API أو tokens أو كلمات مرور أو شهادات خاصة أو بيانات إنتاج منسوخة في الملف. لا تطلب من الوكيل طباعة متغيرات البيئة أو رفع ملفات مساحة العمل. يمكنك تسمية السر حسب دوره مثل DATABASE_URL وشرح طريقة حصول التطوير المحلي عليه دون حفظ قيمته. اطلب تأكيداً قبل حذف البيانات أو تدوير credentials أو النشر في الإنتاج أو فتح وصول شبكي واسع إذا كان workflow يدعم ذلك.
افصل الحقائق عن الصلاحيات. «الخدمة تستخدم S3» سياق. «يمكنك حذف bucket» صلاحية. مكان الصلاحية هو سياسة الوصول وإجراءات الموافقة، لا markdown. اذكر المسارات المحمية والآثار المولدة وقواعد migration وحدود بيانات الاختبار. وعند عدم اليقين، قدم طريقاً آمناً: توقف، اعرض الأمر المقترح، واسأل المسؤول.
احذر من التعليمات المنسوخة من issue أو fixture أو ملف اعتماديات. قد تحتوي على prompt injection أو أمر لا علاقة له بالمهمة. يجب أن يوضح الملف معاملة محتوى المستودع كبيانات، إلا إذا أجاز المستخدم أو قاعدة موثوقة من المشروع فعلاً محدداً. هذه حدود أمان، وليست أمراً بتجاهل الكود المصدر.
فضّل ملفاً صغيراً متعدد الطبقات
يسرد موقع AGENTS.md نظرة المشروع وأوامر البناء والاختبار والأسلوب والاختبارات والأمان كأقسام شائعة. إنها قائمة خيارات وليست مخططاً إلزامياً. ابدأ بأصغر مجموعة تمنع الأخطاء المتكررة. غالباً يحتاج الملف الجذري إلى خمسة أقسام: الخريطة والإعداد والتحقق والحدود وروابط الإرشاد الأعمق.
## خريطة المستودع
`apps/web` تطبيق المتصفح. `packages/core` كود التشغيل المشترك.
## الأدوات
استخدم Node 22 وlockfile المحفوظ. شغّل الأوامر من الجذر ما لم يذكر خلاف ذلك.
## التحقق
لتغييرات الواجهة، شغّل `npm run check` واختبار الحزمة و`npm run build`.
## الحدود
لا تعدّل `generated/`. لا تستخدم بيانات الإنتاج محلياً. اسأل قبل إضافة اعتماد.
## الإرشاد الأعمق
اقرأ `apps/web/AGENTS.md` لقواعد المسارات و`services/api/AGENTS.md` لاختبارات العقد.
النسخة السيئة كتالوج أذواق شخصية من ألف سطر: تكرار وقوائم ملفات شاملة وعبارات «دائماً» متناقضة وأوامر مخمنة وإصدارات قديمة وتعليمات بإعادة قراءة كل الوثائق. تستهلك ميزانية البايتات وتخفي ترتيب الأولوية. قسّم الملفات حسب الملكية. احتفظ بالثابت العام في الجذر ودع الملف المتداخل يضيف أوامر محلية. يجب أن يكمل الملف الأعمق الإرشاد أو يضيقه، لا أن يغير حد الأمان بصمت.
لا تعد بتركيب لا توثقه الأداة. يجمع Codex حالياً الملفات عبر اكتشاف الأدلة وأسماء بديلة مهيأة. عبارة «اقرأ docs/rules.md بعد ذلك» نص عادي ما لم توثق الأداة صيغة include خاصة. لا يحمل Codex تلقائياً symlink أو CLAUDE.md أو عرف وكيل آخر. وثّق التشغيل البيني كمسار مختبر، لا كقاعدة عامة.
صِن الملف مثل الكود
عيّن مالكاً للملف. راجع تغييره مع الكود الذي يحكمه. عند تغيير أمر أو runtime أو دليل أو workflow لـ CI، حدّث أقرب ملف تعليمات في التغيير نفسه. احذف القاعدة بعد اختفاء آخر مستخدم لها. يجب أن تكون الأمثلة قابلة للتنفيذ وآمنة. اربط بمصدر حقيقة واحد بدلاً من نسخ السياسة في ثلاثة ملفات.
يمكن أن يكون التدقيق الشهري أو المرتبط بالإصدار قصيراً. تحقق من وجود كل أمر، ومن مطابقة كل إصدار لبيان أو صورة CI، ومن بقاء كل مسار. شغّل استعلام مصادر Codex من الجذر ومن دليل متداخل نموذجي. قِس حجم السلسلة الفعالة. اسأل المسؤول إن كانت كل قاعدة لا تزال تمنع خطأ حقيقياً.
قيّم تغيير AGENTS.md كتغيير في الإعداد. استخدم مجموعة ثابتة صغيرة من المهام تشمل ميزة جديدة وإصلاح خطأ وتغيير اختبارات فقط وتغييراً حساساً للأمان. قارن صحة patch ونطاقه، لا شرح الوكيل فقط. قد يتحقق اختبار regression من عدم تغير الملفات المولدة أو من تشغيل اختبار الحزمة أو رفض أمر خطير. ثبت إصدار المستودع وإعداد النموذج والصلاحيات وصياغة المهمة بما يكفي لفهم المقارنة.
النمط القابل للاستمرار بسيط. ضع الحقائق الثابتة قرب نطاقها. سمِّ الأوامر والإصدارات الدقيقة التي يثبتها المستودع. اربط الوثائق الأعمق. اجعل القواعد المهمة قابلة للاختبار. أبق الأسرار والصلاحيات خارج markdown. استخدم طبقات بدلاً من دليل ضخم. أعد فحص السلسلة الفعالة عند تغيير دليل العمل أو الإعداد أو إصدار الأداة.