دليل ملف القواعد AGENTS.md: تثبيت القواعد في سلوك Codex
📚 تنقل السلسلة: المقال السابق 10 · العمل السحابي Codex Cloud شرح بالتفصيل مسار تفويض المهام سحابيًا واستلام طلبات PR. يعود هذا المقال لمساحة العمل المحلية لمناقشة ملف هام ينبغي توفره في كل مشروع، ولكن يسيء كتابته أغلب المطورين الجدد — وهو ملف
AGENTS.mdالذي يقرأه Codex كدليل إرشادي قبل البدء في معالجة أي مهمة.
دعونا نتحدث عن خطأ بسيط وقعت فيه عندما بدأت استخدام Codex للمرة الأولى.
في العام الماضي، أسندت مشروع Node.js لـ Codex، وكتبت ملف AGENTS.md في المجلد الرئيسي بوضوح شديد، وسجلت في السطر الأول عبارة صارمة: «يعتمد هذا المشروع على pnpm، ويُحظر استخدام npm تمامًا». ولكن سرعان ما بدأ الوكيل العمل بتشغيل أمر npm install. ظننت حينها أنه لم يقرأ الملف، وقمت بنسخ القاعدة ثلاث مرات وجعلت الخط عريضًا وأضفت علامات تعجب متعددة لتنبيهه، ولكن دون جدوى.
وبعد قضاء وقت طويل في البحث والتدقيق، اكتشفت السبب — لقد قرأ الوكيل الملف بالفعل، ولكنني قمت بدفن هذه القاعدة في السطر 140! حيث ملأت مقدمة الملف بتفاصيل حول تاريخ الشركة، ومخطط تطوير المنتجات، وتفاصيل اختيار التقنيات في صفحات طويلة. وعند وصول Codex لسطر «حظر استخدام npm»، كانت كامل قدرته على التركيز والاستيعاب قد استُهلكت وتبددت في تلك المقدمات الطويلة. ولم تكن المشكلة إذن في عدم التزام الوكيل، بل في قيامي بدفن القاعدة الهامة الوحيدة وسط ركام من المعلومات غير المفيدة.
يمثل ملف AGENTS.md لـ Codex نفس مفهوم ملف CLAUDE.md لـ Claude Code، فهو نفس المفهوم ولكن بمسماين مختلفين. ولكن يتميز Codex بآليات حصرية لاكتشاف الملفات، وقواعد تجاوز الصلاحيات، وحدود حجم الملفات التي تنفرد بها بيئة العمل. وسيوضح هذا المقال القواعد والآليات بالتفصيل مع توضيح المحتويات المناسبة للكتابة.
بعد قراءة هذا المقال，你会拿到：
- مسار اكتشاف Codex لملفات
AGENTS.mdبالكامل (المستوى العام ← مستوى المشروع ← ترتيب الدمج)، وتحديد الأولوية عند حدوث تعارض. - آلية التجاوز المؤقت بملف
AGENTS.override.mdغير المتوفرة في Claude Code، والسيناريوهات المناسبة لاستخدامها. - قائمة إرشادات تفصيلية حول «ما يجب كتابته وما يجب تجنبه» لتفادي دفن القواعد المهمة وسط النصوص غير المفيدة.
- كيفية تعديل مسميات الملفات المسموحة (
project_doc_fallback_filenames) وتعديل الحد الأقصى لحجم الملفات (project_doc_max_bytes) في الإعدادات. - خطوات عملية متكاملة للتأكد من نجاح وقراءة Codex لقواعد ملفات المشروع بدقة.
ملاحظة: يركز هذا المقال على كيفية صياغة ملف AGENTS.md وآلية تحميله فقط. ويتشابه هذا الملف مع ميزة «التذكر التلقائي (Memories)» (وهي طبقة تذكر محلية تكون مغلقة افتراضيًا) المشروحة في المقال 02، وتذكر دائمًا: أن القواعد الأساسية التي يجب تطبيقها بشكل دائم ومستمر يجب كتابتها في ملف AGENTS.md حصريًا، وتجنب الاعتماد على ميزة التذكر التلقائي.
01 أولاً: ملف AGENTS.md كدليل إرشادي وقائمة تسليم للمهام
الخلاصة أولاً: يمثل ملف AGENTS.md توجيهات عامة دائمة تكتبها لـ Codex، ويقوم بقراءتها واستيعابها بالكامل مع كل تشغيل لبناء سياق عمل متكامل حول متطلبات المشروع.
ولماذا نحتاج لهذا الملف؟ لأن Codex يبدأ بصفحة خالية تمامًا مع كل تشغيل جديد (ويطلق لفظ «دورة التشغيل (run)» تقنيًا على كل جلسة عمل أو تشغيل جديد للواجهة التفاعلية). فجميع الإرشادات الشفهية التي وجهتها له في الجلسة السابقة مثل «استخدم pnpm، تجنب لمس مجلد legacy/، وشغل الاختبارات بهذه الصيغة» ينساها الوكيل بالكامل فور إغلاق الجلسة. وغياب ملف AGENTS.md يضطرك لإعادة توجيه وشرح هذه القواعد مع كل مهمة جديدة.
تشبيه: ورقة تسليم المهام بين الورديات. في المصانع التي تعمل بنظام الورديات المتتالية، يسجل المطور في نهاية الوردية القواعد الأساسية على لوحة الإعلانات بوضوح — مثل «تجنب تشغيل الماكينة الفلانية لوجود عطل، تفحص جودة المواد الخام أولاً، ورقم هاتف الطوارئ هو كذا». وبتولى الوردية التالية العمل، تقرأ اللوحة وتلتزم بالتعليمات دون الحاجة لاستدعاء المطورين السابقين للاستفسار. ويمثل ملف AGENTS.md لوحة تسليم المهام لـ Codex — ويقوم بقراءتها بانتظام قبل بدء كل دورة عمل جديدة.
ومتى يتعين عليك إضافة قواعد جديدة للملف؟ نلخص الإشارات العملية في التالي:
- تكرار الوكيل لخطأ معين للمرة الثانية — يتعين تدوين وتثبيت القاعدة هنا لتفادي تكراره مستقبلاً.
- اضطرارك لكتابة نفس التوجيه أو التصحيح الذي وجهته له في دورة العمل السابقة.
- ملاحظتك أثناء مراجعة الأكواد لغياب التزام الوكيل بقواعد برمجية واضحة للمشروع.
- انضمام مطور جديد للفريق (أو عودتك للمشروع بعد غياب أشهر) وحاجته لقراءة القواعد الأساسية.
وعن تجربة شخصية: أعتمد على هذا الملف كـ حلقة تغذية راجعة (feedback loop): عندما يقع Codex في فهم خاطئ لبنية المشروع، أتجنب الاكتفاء بتصحيحه في صندوق المحادثة (لأنه سينسى ذلك في الجلسة القادمة)، بل أوجهه لتسجيل وتثبيت هذا التصحيح في ملف AGENTS.md مباشرة. وبتطبيق هذا المسار في مشروع Python لعدة أسابيع، نما حجم ملف AGENTS.md لقرابة عشرين سطرًا تضم كل الأخطاء الشائعة التي فحصها وسجلها ذاتيًا، ولم يعد يكرر الأخطاء في الجلسات اللاحقة كليًا.
💡 الخلاصة في جملة واحدة: يمثل ملف
AGENTS.mdدليل إرشادي وقائمة تسليم لـ Codex قبل بدء كل دورة عمل جديدة، ويتحسن أداؤه ومرونته كلما سجلت فيه القواعد الجديدة تدريجيًا؛ وهو يطابق ملفCLAUDE.mdفي أداة Claude Code.
02 مسار الاكتشاف: كيف يحدد Codex ملفات القواعد
لا تقتصر الأداة على قراءة ملف AGENTS.md واحد، بل تدعم توزيع ملفات القواعد في مسارات متعددة، وتختلف مجالات صلاحياتها من العام للمحدد. ويقوم Codex بربط ودمج هذه الملفات في «سلسلة قواعد متكاملة» مع كل تشغيل — ويتميز هذا النظام عن Claude Code بعدة فروق نوضحها في التالي.
وفقًا للوثائق الرسمية، يسير بناء سلسلة القواعد مع كل تشغيل جديد عبر الخطوات التالية:
أولاً: المستوى العام (Global scope): يتوجه Codex لمجلد الإعدادات العام للمستخدم (المسار الافتراضي ~/.codex ما لم يتم تعديل متغير البيئة CODEX_HOME)، ويبحث عن ملف التجاوز المؤقت AGENTS.override.md أولاً ويقرأه عند تواجده؛ وإذا لم يجده يقرأ ملف القواعد العام AGENTS.md. ويقتصر النظام في هذا المستوى على تحميل ملف واحد غير فارغ وتفادي تحميل الملفين معًا.
ثانياً: مستوى المشروع (Project scope): يبدأ الفحص من المجلد الرئيسي للمشروع (مجلد Git الرئيسي عادة)، ويستمر تدريجيًا للمجلدات الفرعية وصولاً للمجلد المفتوح حاليًا. ويبحث Codex في كل مجلد بالترتيب التالي: ملف AGENTS.override.md أولاً، ثم ملف AGENTS.md، وأخيرًا الملفات البديلة المعرفة في خيار project_doc_fallback_filenames. ويتم تحميل ملف واحد كحد أقصى من كل مجلد.
ثالثاً: ترتيب الدمج (Merge order): يقوم Codex بدمج وتجميع كافة ملفات القواعد المكتشفة بالترتيب من العام إلى الخاص مع الفصل بينها بأسطر فارغة. وتتمتع الملفات القريبة من المجلد الفرعي المفتوح حاليًا بالأولوية القصوى لقراءتها في نهاية السلسلة المدمجة، وتلغي القواعد المتعارضة الواردة في المستويات العليا.
يوضح المخطط مسار الاكتشاف بالكامل: فحص المستوى العام واختيار أحد الملفين، ثم فحص مجلدات المشروع تدريجيًا وجلب ملف واحد من كل مجلد، ودمجها بالكامل في سلسلة متكاملة — لتكون القواعد القريبة من موضع عملك هي الأكثر قوة وتأثيرًا.
ونوضح قاعدتين أساسيتين تنص عليهما الوثائق الرسمية:
- أولاً: الدمج لا الإلغاء الشامل: يتم تفعيل وتطبيق ملف القواعد العام والملفات الخاصة بالمشروع معًا بالتوازي، ولا يؤدي كتابة ملف خاص بالمشروع لإلغاء ملف القواعد العام. بل يتم دمج محتويات الملفين معًا في السياق، وعند تعارض قاعدتين محددتين يتم تطبيق القواعد الواردة في الملف القريب (الخاص بالفرعي).
- ثانياً: الأولوية للأقرب: إذا حدد ملف القواعد العام
AGENTS.mdقاعدة «استخدام علامات الاقتباس المفردة»، بينما حدد ملف المشروعAGENTS.mdقاعدة «استخدام علامات الاقتباس المزدوجة» — فسيتم تطبيق علامات الاقتباس المزدوجة لكون ملف المشروع أقرب لموضع العمل ويقرأ لاحقًا. وتسهل هذه الميزة صياغة قواعد مخصصة للمشاريع تتجاوز التفضيلات الشخصية العامة للمطور.
يوضح الشكل دمج المستويات الثلاثة بالترتيب — المستوى العام (~/.codex/)، المجلد الرئيسي للمشروع، والمجلدات الفرعية بالتتابع، مع بقاء فاعلية المستويات الثلاثة بالتوازي؛ ويوضح سهم «الأولويات والأولى بالتطبيق» أن الملفات القريبة لموضع العمل تقرأ وتدمج لاحقًا في نهاية السلسلة، مما يمنحها الأولوية للتطبيق عند التعارض، وهذا ما يسمى «التجاوز بالقرب».
💡 الخلاصة في جملة واحدة: يسير مسار اكتشاف القواعد كالتالي: فحص المستوى العام (مجلد
~/.codex/مع أولوية للملف المؤقت)، ثم فحص مستودع المشروع تدريجيًا من المجلد الرئيسي للمجلدات الفرعية، وتدمج كافة القواعد المكتشفة بالترتيب مع منح القواعد القريبة الأولوية للتحميل والتطبيق.
03 التجاوز المؤقت بملف AGENTS.override.md
تكرر ذكر ملف AGENTS.override.md في الأقسام السابقة. ويعد هذا الملف ميزة حصرية لـ Codex لا تتوفر لها بدائل في أداة Claude Code، ونفصل استخداماته في التالي.
ما هي المشكلة التي يحلها هذا الملف؟ لنفترض أنك كتبت قواعد وتفضيلات برمجية عامة في ملف ~/.codex/AGENTS.md وتعمل بها بانتظام. ولكنك ترغب اليوم في العمل على مشروع مخصص يتطلب تعديل وتجاوز كامل القواعد العامة السابقة مؤقتًا، دون الرغبة في حذف أو تعديل ملف القواعد العام لتفادي إعادة كتابته لاحقًا. فكيف تعالج هذا التعارض؟
تشبيه: وضع ملصق ملاحظات مؤقت فوق المستند. يظل المستند الأصلي محفوظًا في الدرج دون تعديل أو تمزيق؛ وتكتفي بلصق ورقة ملاحظات صغيرة فوقه قائلًا «يتم التزام القواعد المذكورة هنا مؤقتًا لهذا العمل». وفور انتهاء العمل، تنزع ورقة الملاحظات ليعود العمل بالمستند الأصلي تلقائيًا. ويمثل ملف AGENTS.override.md ورقة الملاحظات المؤقتة هذه — فعند تواجده، يتم تجاهل ملف AGENTS.md المتواجد في نفس المجلد بالكامل؛ وفور حذفه، يعود العمل بالملف الأصلي فورًا.
وتقترح الوثائق حالتين عمليتين للاستخدام:
- التجاوز المؤقت للمستوى العام: بكتابة القواعد المؤقتة في ملف
~/.codex/AGENTS.override.mdلتجاوز ملف~/.codex/AGENTS.mdالعام مؤقتًا دون تعديله، وحذف الملف المؤقت فور انتهاء العمل لاستعادة الإعدادات العامة. - تحديد قواعد خاصة لمجلدات فرعية: للمجلدات التي تتطلب قواعد برمجية تختلف كليًا عن بنية المشروع العامة. مثل مجلد المدفوعات
services/payments/بكتابة ملفAGENTS.override.mdداخله كالتالي:
# services/payments/AGENTS.override.md
## قواعد معالجة المدفوعات
- استخدم أمر `make test-payments` لتشغيل الاختبارات بدلاً من `npm test`
- يرجى إخطار فريق الحماية الأمنية مسبقًا قبل تجديد مفاتيح API Keysوبتوفير هذا الملف المؤقت، يتم تجاهل ملف AGENTS.md المتواجد في نفس المجلد الفرعي بالكامل، ويعتمد Codex على القواعد المسجلة في الملف المؤقت فقط لمعالجة المهام داخل هذا المجلد.
وننبه هنا لمفهوم خاطئ يقع فيه المبتدئون: لا يؤدي ملف التجاوز المؤقت override لإلغاء كامل سلسلة الملفات في المجلدات الأخرى:
| النطاق والمستوى | تأثير وسلوك ملف AGENTS.override.md |
|---|---|
| داخل نفس المجلد | عند تواجده ← يتم تجاهل ملف AGENTS.md (والملفات البديلة) المتواجد في نفس المجلد، ويتم قراءة الملف المؤقت فقط |
| عبر المجلدات الأخرى (كامل السلسلة) | لا يؤدي لحجب أو مسح القواعد المعرفة في المجلدات العليا أو العامة؛ بل يتم دمجها بالتتابع كالمعتاد وتطبيق الأقرب عند التعارض |
وبعبارة أخرى: ينحصر سلوك ملف override في قوله «استخدم القواعد المكتوبة بداخلي وتجاهل ملف AGENTS.md المتواجد معي في نفس المجلد»، ولا يمنع دمج الملفات المتواجدة في المجلدات الأخرى. وتستمر سلسلة الدمج وقواعد الأولوية للأقرب في العمل كالمعتاد. ولقد أسأت فهم هذا السلوك في البداية وظننت أن تفعيل ملف override في مجلد فرعي سيحجب قواعد الملف العام، واكتشفت استمرار دمج قواعد الملف العام لاحقًا بعد مراجعة الوثائق وتأكيد انحصار عمله في نفس المجلد المدمج.
وتبرز فائدة هذا الملف عند تتبع الأعطال: فإذا لاحظت قيام Codex بتشغيل مهام أو التزام قواعد غريبة لم تسجلها، فابحث في المجلدات العليا تدريجيًا وصولاً لمجلد ~/.codex للتأكد من عدم وجود ملف AGENTS.override.md مخفي يملي هذه التوجيهات. ويكفي حذفه أو تعديل اسمه لاستعادة قواعد ملفات AGENTS.md الرسمية.
💡 الخلاصة في جملة واحدة: يمثل ملف
AGENTS.override.mdأداة للتجاوز المؤقت — وعند تواجده في مجلد، يتم حجب وتجاهل ملفAGENTS.mdالمقابل له في نفس المجلد فقط دون التأثير على عمليات دمج الملفات في المجلدات الأخرى؛ ويستخدم لتجنب تعديل الملفات الأصلية، ومسحه يستعيد القواعد الافتراضية فورًا.
04 صياغة المحتوى: القواعد المقبولة وتلك التي يجب تجنبها
يعد هذا القسم الأهم لتجنب كتابة ملفات مطولة غير مفيدة. فتعطل أو تجاهل ملفات القواعد يرجع بنسبة كبيرة لصياغة توجيهات غير دقيقة أو حشو ملفات القواعد بتفاصيل لا تخدم العمل البرمجي.
أولاً: المحتويات التي ينصح بكتابتها — الخلاصة: اكتب «القواعد والحقائق الأساسية التي يجب على Codex الالتزام بها في كل دورة عمل». ونلخصها في خمسة جوانب:
| الجانب البرمجي | التفاصيل والمحتويات | أمثلة توضيحية |
|---|---|---|
| وصف المشروع | شرح مبسط في جملة واحدة لوظيفة المشروع | «نظام خلفي لإدارة الطلبات يعتمد على FastAPI» |
| التقنيات المستخدمة | تحديد إصدارات اللغات، أطر العمل، قواعد البيانات، والأدوات | «Python 3.11 / PostgreSQL / pytest» |
| الأوامر الشائعة | صيغة تشغيل الاختبارات، البناء، الفحص البرمجي، وتنسيق الأكواد | npm run lint ، make test-payments |
| معايير التنسيق | نمط كتابة الكود، التسميات، والمواصفات المعتمدة | «تحديد الأنواع لكل المعاملات»، «استخدام علامات الاقتباس المزدوجة للنصوص» |
| المحظورات البرمجية | الملفات المحمية من التعديل، والعمليات التي تتطلب استئذانًا مسبقًا | «يُحظر تعديل الملفات السابقة في مجلد migrations/»، «استأذن مسبقًا قبل إضافة حزم جديدة» |
وتعد الأوامر الشائعة الأكثر أهمية للوكيل — حيث يقرأها Codex لتشغيل الاختبارات وبناء المستودع وتهيئة طلبات PR لمنع استخدام أوامر خاطئة أو عشوائية. ويضم دليل القواعد الرسمي مثالاً للأوامر في السطر الأول: «شغل أمر npm run lint قبل رفع طلب PR». بينما تمثل قائمة المحظورات صمام الأمان لمنع التعديلات العشوائية: كحظر تعديل الأكواد القديمة الموروثة وتحديد العمليات الحساسة التي تتطلب طلب الإذن مسبقًا.
ثانياً: المحتويات التي يجب تجنب كتابتها لتفادي هدر المساحة وتبديد التركيز:
- ❌ المقدمات والتفاصيل التاريخية المطولة: كتاريخ تأسيس الشركة، ورؤية المنتج، وقصص اختيار التقنيات — فلن يستفيد منها الوكيل في كتابة الأكواد، وتؤدي لاستهلاك سياق المحادثة وتشتيت تركيز الوكيل عن القواعد الهامة.
- ❌ المعلومات القديمة غير المحدثة: مثل إبقاء قواعد npm داخل الملف بعد تحويل المشروع لاستخدام pnpm، مما يضلل الوكيل ويؤدي لفشل البناء.
- ❌ القواعد البرمجية البديهية: مثل شرح بنية المجلدات ووظيفة كل ملف بالتفصيل، أو نسخ إعدادات أدوات التنسيق مثل ESLint أو Prettier. حيث يستطيع Codex قراءة وتحليل بنية الأكواد ذاتيًا، وإعادة تدوينها يهدر مساحة السياق دون فائدة.
وتحدد الوثائق الرسمية حدودًا لحجم ملف القواعد لتفادي هدر الموارد، ولكن تختلف هذه الحدود عن Claude Code (الذي يوصي بحدود 200 سطر)، حيث يعتمد Codex على حساب حجم الملف بالبايت (Bytes):
يتجاهل Codex الملفات الفارغة تلقائيًا. وفور وصول إجمالي حجم الملفات المدمجة للحد الأقصى المعرف في متغير project_doc_max_bytes (الافتراضي 32 KiB)، يتوقف النظام عن جلب ودمج أي ملفات إضافية.
وننبه لمعنيين هامين في هذا القيد: أولاً أن الحد الأقصى هو 32 KiB للإجمالي، وتجاوزه يؤدي لقطع النصوص وحجب الملفات اللاحقة؛ وثانيًا أن الحساب يشمل إجمالي الملفات المدمجة بالكامل (المستوى العام ومستوى المشروع والمجلدات الفرعية مجتمعة). لذا فإن صياغة ملفات ضخمة في المستويات العليا قد يمنع تحميل القواعد الخاصة للمجلدات الفرعية لاحقًا. وتنصح الوثائق عند بلوغ الحد الأقصى: بتعديل ورفع قيمة project_doc_max_bytes في الإعدادات، أو توزيع القواعد على مجلدات فرعية متعددة (مما يقلل استهلاك الرموز ويحافظ على تنظيم القواعد).
وأعتمد على قاعدة ذهبية بسيطة عند صياغة القواعد: «هل يستطيع Codex استنتاج هذه القاعدة بمجرد فحص كود المشروع؟ إذا كانت الإجابة نعم، فاحذفها فورًا». وتطبيق هذا الفحص يقلل حجم ملفات القواعد الضخمة لعشرات الأسطر المركزة فقط، ويمنع وقوع الوكيل في أخطاء البناء أو تشغيل حزم خاطئة.
💡 الخلاصة في جملة واحدة: سجل القواعد والحقائق الأساسية للمشروع (الوصف، التقنيات، الأوامر، معايير التنسيق، والمحظورات)، واحذف القواعد البديهية التي يستنتجها الوكيل من فحص الكود؛ وتذكر أن الحد الأقصى الافتراضي لدمج الملفات هو 32 KiB ويُعدل بمتغير
project_doc_max_bytesعند الحاجة.
05 خيارات الإعداد: تعديل الأسماء وتعديل حد الحجم
يكفي استخدام التسميات والحدود الافتراضية لأغلب المشاريع. ولكن عند الحاجة لتخصيصها، توفر الإعدادات خيارين لضبطهما في ملف الإعدادات العام للمستخدم ~/.codex/config.toml.
أولاً: تعريف مسميات ملفات القواعد المخصصة
لنفترض أنك كتبت قواعد وتفضيلات برمجية عامة في ملف ~/.codex/AGENTS.md وتعمل بها بانتظام. وتفاديًا لإنشاء ملف AGENTS.md جديد وتكرار القواعد بداخله، يمكنك توجيه Codex لقراءة واستيعاب ملف TEAM_GUIDE.md مباشرة بتعديل خيار project_doc_fallback_filenames في ملف التكوين:
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]وبإدراج هذه الأسماء، يصبح ترتيب فحص الملفات في المجلدات كالتالي: ملف AGENTS.override.md ← ملف AGENTS.md ← ملف TEAM_GUIDE.md ← ملف .agents.md، ويتم تحميل أول ملف متواجد غير فارغ بالترتيب.
تنبيه هام: يتجاهل Codex أي ملفات إرشادية لا تدرج أسماؤها في هذه القائمة. فلن يتم قراءتها أو دمجها في سياق العمل تلقائيًا ما لم تسجل التسمية بدقة في خيار
project_doc_fallback_filenames.
ثانياً: تعديل الحد الأقصى لحجم الملفات المدمجة
كما وضحنا سابقًا، يبلغ الحد الأقصى الافتراضي لحجم الملفات المدمجة 32 KiB. وإذا تجاوزت القواعد هذا الحد وترغب في تحميلها كاملة دون تجزئتها مؤقتًا، فيمكنك رفع القيمة المحددة لمتغير project_doc_max_bytes:
# ~/.codex/config.toml
project_doc_max_bytes = 65536ويرفع هذا الإعداد حد الحجم لـ 64 KiB لاستيعاب قواعد أوسع. ولكن ننصح باعتبار بلوغ الحد الإشعار الأهم لتبسيط وتخفيف القواعد أو توزيعها فرعيًا بدلاً من الاكتفاء برفع القيمة التقنية للحد. والتوجه الصحيح يفضل تبسيط وحذف الحشو أولاً، وتوزيع الملفات فرعيًا، وتأجيل رفع القيمة كخيار أخير للمشاريع الضخمة.
نلخص السيناريوهات المناسبة لتعديل الخيارات في التالي:
| الحالة والهدف | الإجراء المناسب في الإعدادات |
|---|---|
الرغبة في اعتماد ملف إرشادات مخصص متواجد مسبقًا مثل TEAM_GUIDE.md | أضف الاسم لقائمة خيار project_doc_fallback_filenames |
| تعرض قواعد المشروع للحجب أو القطع لتجاوزها حد 32 KiB | يفضل تبسيط القواعد أو توزيعها فرعيًا أولاً؛ وارفع حد project_doc_max_bytes عند الضرورة |
| الرغبة في اعتماد بيئة إعدادات مستقلة بالكامل لمستخدم آخر | عدل متغير البيئة CODEX_HOME ليوجه لمجلد إعدادات مخصص (كما سنوضح في التمرين) |
⚠️ بعد تعديل ملف
config.tomlتأكد من إعادة تشغيل Codex. حيث يتم قراءة ملفات التكوين عند بدء التشغيل فقط، وغياب إعادة التشغيل يمنع تفعيل التعديلات الجديدة.
💡 الخلاصة في جملة واحدة: يتيح خيار
project_doc_fallback_filenamesتعريف مسميات ملفات القواعد المخصصة (ويتم تجاهل أي اسم خارج القائمة)، ويتيح متغيرproject_doc_max_bytesتعديل حد الحجم الإجمالي (الافتراضي 32 KiB)، ويتطلب تفعيل التعديلات إعادة تشغيل الأداة.
06 تمرين عملي: إنشاء وتأكيد تفعيل ملف AGENTS.md لمشروع تجريبي
سنطبق الآن خطوات عملية متكاملة لإنشاء ملف قواعد مبسط لمشروع تجريبي وفحص تفعيله وقراءته بواسطة Codex بنجاح. اتبع الخطوات التالية:
نوصي في نظام Mac / Linux بتشغيل الأوامر مباشرة؛ ولنظام Windows يفضل تشغيلها داخل Git Bash أو بيئة WSL، أو إنشاء المجلدات والملفات يدويًا من واجهة النظام. ويشير الرمز ~ لمجلد المستخدم الرئيسي (ويقابل المسار C:\Users\username\ في Windows).
الخطوة الأولى: إنشاء مجلد تجريبي وتهيئته كمستودع Git
mkdir agents-md-demo
cd agents-md-demo
git initالمتوقع: إنشاء مجلد .git مخفي داخل مجلد المشروع التجريبي. وتكمن أهمية تهيئة Git في تمكين Codex من التعرف على المجلد كـ «مجلد رئيسي للمشروع» (حيث يبدأ الفحص من مجلد Git الرئيسي)، وتسهيل حفظ ومشاركة ملف AGENTS.md مع فريق العمل.
الخطوة الثانية: كتابة ملف قواعد مبسط ومختصر
أنشئ ملف AGENTS.md في المجلد الرئيسي للمشروع، وسجل بداخله القواعد التالية (لاحظ حجم واختصار الملف — وهو النموذج الصحيح لصياغة القواعد):
# agents-md-demo — مشروع تجريبي مبسط
يقتصر هذا المشروع على توضيح آلية صياغة وقراءة ملف AGENTS.md، ويخلو من الأكواد البرمجية الحقيقية.
## الأوامر الشائعة
- `npm test` —— لتشغيل اختبارات المشروع
## معايير التنسيق
- يجب تحديد الأنواع لكافة المعاملات في الدوال البرمجية
- التزام استخدام علامات الاقتباس المزدوجة للنصوص دائماً
## محظورات برمجية
- يُحظر إضافة أي حزم خارجية لبيئة الإنتاج دون مراجعة مسبقة معيالمتوقع: حفظ ملف AGENTS.md في المجلد الرئيسي للمشروع بالصيغة المكتوبة. وتذكر دائمًا إبقاء حجم الملف مختصرًا في حدود أسطر قليلة لتفادي تشتيت الوكيل.
الخطوة الثالثة: توجيه Codex لتأكيد قراءة القواعد
توفر الأداة أمرًا مباشرًا لفحص وتأكيد قراءة القواعد الفعالة للجلسة. شغل الأمر التالي في مجلد المشروع:
codex --ask-for-approval never "Summarize the current instructions."المتوقع: يقوم Codex بقراءة وتلخيص القواعد التي سجلتها (صيغة الاختبارات، معاملات الأنواع، علامات الاقتباس، وحظر الحزم الخارجية) وعرضها في صندوق المحادثة. ورؤية التلخيص تؤكد نجاح قراءة ودمج ملف AGENTS.md في سياق الجلسة الحالية.
ℹ️ ملاحظة: نستخدم خيار
--ask-for-approval neverهنا لتفادي توقف المعالجة لطلب الإذن وعرض التلخيص مباشرة لتسهيل التمرين، وتجنب تفعيل هذا الخيار للمشاريع الحقيقية للحفاظ على سلامة الملفات ومراجعة التعديلات مسبقًا.
الخطوة الرابعة (متقدمة): تأكيد أولوية تطبيق قواعد الملف القريب
لتأكيد ميزة الأولوية للأقرب بشكل عملي، سننشئ مجلدًا فرعيًا ونضيف ملف تجاوز مؤقت خاص به:
mkdir -p services/paymentsوفي مسار services/payments/AGENTS.override.md اكتب القواعد التالية:
# services/payments/AGENTS.override.md
## قواعد معالجة المدفوعات
- استخدم أمر `make test-payments` لتشغيل الاختبارات بدلاً من `npm test`وشغل أمر فحص القواعد والملفات المحملة من داخل هذا المجلد الفرعي:
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."المتوقع: يعرض Codex قائمة بمسارات كافة الملفات التي تم دمجها بالترتيب — بدءًا بملف المستوى العام (عند تواجده)، ثم ملف المشروع الرئيسي، وأخيرًا ملف التجاوز المؤقت للمجلد الفرعي. وسيؤكد التقرير اعتماد أمر make test-payments لتشغيل الاختبارات وتجاهل أمر npm test المعرف في المجلد الرئيسي، مما يثبت ميزة «الأولوية للأقرب» عمليًا.
⚠️ دليل فحص الأعطال عند تعذر تفعيل القواعد:
- شغل أمر
Summarize the current instructionsللتأكد من نجاح جلب الملفات.- شغل أمر
codex statusللتأكد من صحة مسار المجلد الرئيسي المعتمد للمشروع.- ابحث في المجلدات العليا عن ملفات
AGENTS.override.mdمخفية قد تحجب القواعد.- تأكد من أن الملف يحتوي على نصوص برمجية (حيث يتجاهل Codex الملفات الفارغة تلقائيًا).
07 ملخص
لخص هذا المقال تفاصيل وقدرات صياغة ملفات القواعد لـ Codex:
| الجانب البرمجي | التوضيح والخلاصة الفنية |
|---|---|
| المفهوم الأساسي | ملف توجيهات عامة يقرأه Codex مع كل تشغيل، ويطابق ملف CLAUDE.md في الأداة الأخرى |
| مسار الاكتشاف | يبدأ من المستوى العام (مجلد ~/.codex مع أولوية للملف المؤقت) ← ثم فحص مستودع Git تدريجيًا من الرئيسي للفرعي |
| آلية الدمج | يتم دمج القواعد معًا بالتتابع، وعند تعارض قاعدتين يتم تطبيق القواعد الواردة في الملف القريب (الخاص بالفرعي) |
| الملف المؤقت override | ميزة حصرية لـ Codex: تؤدي لحجب ملف AGENTS.md المقابل في نفس المجلد فقط دون مسح الملفات في المجلدات الأخرى |
| محتويات الملف | الوصف، التقنيات，الأوامر，معايير التنسيق، والمحظورات؛ واحذف القواعد البديهية التي يستنتجها الوكيل من الكود |
| حد الحجم المسموح | يُحسب بالبايت لإجمالي الملفات المدمجة بحد أقصى 32 KiB ويُعدل بمتغير project_doc_max_bytes |
| خيارات الإعداد | خيار project_doc_fallback_filenames لتعريف الأسماء، ومتغير project_doc_max_bytes للحجم، ويتطلب تفعيلهما إعادة التشغيل |
يجب أن تكون قادرًا الآن على: صياغة قواعد برمجية مركزة وواضحة للمشروع وتحديد المستوى المناسب لكتابتها، فهم آلية دمج الملفات وتحديد الأولويات عند التعارض، استخدام ملفات التجاوز المؤقت override لتعديل القواعد دون لمس الملفات الأصلية، تنظيم وتبسيط القواعد لتفادي حدود الحجم المسموحة، وتوجيه الوكيل لتأكيد قراءة القواعد بنجاح. وبإتمام هذا المقال، أصبحت قادرًا على صياغة ملفات قواعد منظمة ودقيقة يلتزم بها Codex بالكامل لتسهيل كتابة الأكواد.
المقال التالي 12 · الأوامر المائلة والاختصارات — لقد تدربنا على استخدام أوامر سطر الأوامر codex ... في هذا المقال، ولكن ماذا عن الأوامر المتاحة داخل الجلسة التفاعلية؟ سيوضح المقال القادم الأوامر المائلة التي تبدأ بـ / لتعديل الأوضاع، ومسح السياق، ومراجعة الحالة، بالإضافة لاختصارات لوحة المفاتيح المفيدة لتسريع العمل. وسؤال للتفكير: نعتمد على كتابة الملفات لحفظ وتثبيت القواعد بشكل دائم، فإذا أردت تعديل سلوك الوكيل مؤقتًا للجلسة الحالية فقط دون تعديل ملفات القواعد، ما هي الطريقة المناسبة لذلك؟