أفضل الممارسات: الإجراءات القابلة للتطبيق الفعلي بعيدًا عن «النصائح العامة المكررة»
📚 التنقل في السلسلة: لخصت المقالة السابقة 35 دليل الأوامر والتكوين السريع الأوامر ومفاتيح التكوين واختصارات لوحة المفاتيح في جدول متكامل يمكن تثبيته على الحائط. وتأتي هذه المقالة لتنتقل لمستوى آخر — لا تشرح «ما هي الميزات المتوفرة»، بل توضح «كيفية ربط الميزات واستخدامها معًا لتوفير وقتك وجهدك الفعلي عبر Codex». وتتحدث المقالة التالية 37 تتبع المشاكل الشائعة وإصلاحها عن «ماذا تفعل عند حدوث خطأ».
بصراحة، قمت بأمر غبي للغاية عندما حصلت على Codex لأول مرة: قرأت صفحة أفضل الممارسات (best-practices) الرسمية من البداية للنهاية، وشعرت أن كل نصيحة منطقية للغاية، ثم... أغلقت الصفحة، ولم أغير أي شيء في طريقة استخدامي الفعلية.
المشكلة لم تكن فيّ — بل في أن أغلب ما يسمى بأفضل الممارسات هو عبارة عن نصائح عامة مكررة وبديهية: «صغ طلبك بوضوح»، «تذكر تشغيل الاختبارات»، «اعمل بخطوات مصغرة» — كلها تبدو صحيحة، ولكنها لا توضح لك مدى الوضوح المطلوب، وما الذي يجب اختباره، ومدى صغر الخطوة المطلوبة. فتكتفي بهز رأسك موافقًا وتعود للعمل بنفس الأسلوب القديم. ومثل هذه النصائح العامة تعيد مسؤولية اتخاذ القرار إليك في النهاية.
لذا لا أنوي في هذه المقالة تكرار تلك النصائح العامة التي يمكن لأي شخص قولها. بل قمت بقراءة دليل أفضل الممارسات الرسمي بالكامل، واستخلصت منه النقاط التي غيرت أسلوب عملي فعليًا وقمت بالتحقق من نجاحها بنفسي، ونعرض لكل نقطة تفاصيل «سبب القيام بذلك + كيفية التطبيق عمليًا + والمشاكل الناتجة عن إهمالها». ونحتفظ فقط بالنقاط القابلة للتطبيق الفعلي، ونحذف أي نصيحة تبدو جذابة ولكنها غير عملية.
وبصراحة، فإن أغلب النقاط التالية هي نتاج وقوعي في أخطاء مسبقًا وتكبدت عناءها، ثم عدت لتصحيحها والالتزام بها.
بعد قراءة هذه المقالة، ستحصل على:
- طريقة تفكير للتعامل مع Codex كـ «زميل عمل» يحتاج للتوجيه، وليس مجرد «أداة مؤقتة»
- ما الذي يجب كتابته في ملف
AGENTS.md(ملف توجيهات المشروع) وبأي حجم ليكون مفيدًا فعليًا - صيغة تفويض المهمة الرباعية «الهدف + السياق + القيود + القبول» لتعبئتها مباشرة
- كيفية تقسيم الصلاحيات والـ sandbox لعدة مستويات حسب بيئة العمل، وأي مستوى تبدأ به كمبتدئ
- لماذا يجب مطالبته بإعداد خطة عمل أولاً للمهام المعقدة قبل البدء في كتابة الكود
- كيف توجه Codex للاختبار والمراجعة الذاتية، بدلاً من قيامك بمراقبة وتدقيق كل خطوة بنفسك
- كيفية معالجة المشاكل في بيئات الإنتاج: الحصول على الأدلة والتحقق أولاً، وإلغاء حساسية البيانات، ثم التأكيد على الإصلاح
- جدول مقارنة يوضح «أخطاء شائعة ❌ / الممارسة الصحيحة ✅» لتطبيقه مباشرة
⚠️ تعتمد الأوامر ومفاتيح التكوين والسلوك الافتراضي على دليل أفضل ممارسات Codex الرسمي؛ وتتغير أسماء النماذج والحد الأقصى للميزات مع الإصدارات والباقات، لذا اعتمد على ما يظهره أمر
codex --helpولوحة/modelوملف~/.codex/config.tomlالفعلي لديك.
01 تغيير طريقة التفكير أولاً: Codex هو زميل عمل يحتاج للتوجيه المستمر، وليس أداة مؤقتة
الخلاصة أولاً: تعتمد جودة وفائدة Codex إلى حد كبير على كيفية نظرتك وتعاملك معه.
يتعامل الكثيرون معه (بمن فيهم أنا في البداية) كصندوق بحث «يجيب على سؤال محدد»: تمرر له سؤالاً وتأخذ الرد وتغادر، وتبدأ من الصفر في المرة القادمة. والعمل بهذا الأسلوب يحرمك من 70% من قدرات الأداة.
تشبيه: يشبه Codex موظفًا جديدًا انضم لفريق العمل ويتمتع بمهارات قوية ولكنه لا يعرف شيئًا عن طبيعة مشروعك الحالي. لن تتوقع منه استيعاب كل شيء من اليوم الأول — بل يجب تزويده بمليف التوجيهات (دفتر إرشادات العمل AGENTS.md) وتوضيح كيفية تشغيل الكود وكيفية تشغيل الاختبارات، وتصحيح أخطائه وتوجيهه وتدريبه ليستفيد منها مستقبلاً. وكلما زاد وقت توجيهه وتدريبه، عمل بكفاءة وسلاسة أكبر. وعلى العكس، إذا كنت تستعين في كل مرة بموظف مؤقت لا يعرفك، فستضطر لتكرار نفس التوضيحات البسيطة دائمًا.
أوافأق تمامًا على العبارة المذكورة في المستندات الرسمية، ومؤداها: بدلاً من التعامل مع Codex كأداة مساعدة مؤقتة للمرة الواحدة، تعامل معه كزميل عمل تقوم بتهيئة إعداداته وتطوير قدراته باستمرار. ويدور سير العمل في هذه المقالة حول تفعيل هذه الفكرة — بتحويل التعليمات المؤقتة والمتكررة إلى إعدادات وتكوينات دائمة مستقرة.
حدث التحول في أسلوب عملي في بداية عام 2026. فقبل ذلك الوقت، كنت أضطر لكتابة تعليمات متكررة مع كل جلسة جديدة مثل «يستخدم هذا المشروع pnpm وليس npm»، «تشغيل الاختبارات عبر pnpm test»، «يجب كتابة رسالة الـ commit باللغة العربية»، وظللت أكتبها سبع أو ثماني مرات يوميًا. حتى شعرت بالملل وقمت بإضافتها في ملف AGENTS.md لمرة واحدة، وعملت الأداة بسلاسة من حينها — وأدركت أنني كنت أستخدم طريقة بدائية ومرهقة للتعامل مع أداة ذكية للغاية.
💡 الخلاصة في جملة واحدة: يمثل التعامل مع Codex كزميل عمل يحتاج للتوجيه والتدريب المستمر بدلاً من اعتباره أداة مؤقتة أساس كل الممارسات الصحيحة.
02 إعداد ملف AGENTS.md بشكل صحيح: دعه يعمل بتضمين «السياق» تلقائيًا
لماذا نقوم بذلك. يمثل هذا الملف الحل العملي للمشكلة الموضحة في القسم السابق. يمثل ملف AGENTS.md دليل توجيهات المشروع المحفوظ في المجلد الحالي، ويقوم Codex بقراءته تلقائيًا وتضمينه في السياق مع بدء الجلسة، دون الحاجة للإشارة إليه يدويًا عبر رمز @. اكتب القواعد المتكررة للمشروع مرة واحدة في هذا الملف لتصبح فعالة دائمًا.
تشبيه: يمثل ملف AGENTS.md ملف README مخصص للذكاء الاصطناعي. يكتب ملف README العادي للبشر ليوضح لهم طبيعة المشروع وكيفية تشغيله؛ بينما يكتب ملف AGENTS.md لـ Codex ليوضح له القواعد المعمول بها، والمحاذير، ومعايير قبول وإنجاز المهام.
كيفية الإعداد. تنصح التوجيهات الرسمية بتضمين الأجزاء التالية في ملف AGENTS.md المتميز، ورتبها كالتالي:
- هيكل المشروع ومواقع المجلدات الهامة
- كيفية بناء وتشغيل المشروع
- الأوامر المستخدمة للبناء والتشغيل والاختبار وفحص الكود (lint)
- اتفاقيات كتابة الكود ومتطلبات طلبات السحب (PR)
- المحاذير وقواعد «المنع الأمنية» الصارمة
- معايير القبول وشروط انتهاء العمل وكيفية التحقق
أسهل طريقة للبدء هي تشغيل أمر /init في الطرفية (CLI)، وسيقوم بإنشاء هيكل ملف AGENTS.md أساسي في المجلد الحالي. ولكن تجنب استخدامه دون تعديل — فالملف المتولد هو قالب عام، ويجب عليك تخصيصه وكتابة التفاصيل الحقيقية لمشروعك.
ويمكن كتابة ملفات AGENTS.md على مستويات متعددة: حفظ الملف في ~/.codex/ ليمثل إعداداتك الافتراضية الخاصة بك؛ وحفظه في جذر المشروع ليمثل القواعد المشتركة للفريق؛ وحفظه في مجلد فرعي لتحديد قواعد جزئية خاصة بذلك المجلد. وتكون للملف الأقرب لمجلد العمل الحالي الأولوية دائمًا.
مثال خاطئ (وقعت فيه شخصيًا). كان خطئي في البداية هو العكس تمامًا: حيث قمت بكتابة تعليمات مؤقتة وخاصة بالدورة الحالية مثل «لا تقم بتعديل قاعدة البيانات في هذه الخطوة» أو «عدل هذا الملف المحدد فقط» داخل ملف AGENTS.md، وتراكمت هذه التعديلات وأصبح الملف طويلاً ومليئًا بالقواعد منتهية الصلاحية، وتشتت Codex بسبب قراءتها. وتعلمت الدرس بعد ذلك —
اكتب التعليمات المؤقتة والخاصة بالمهمة الحالية في طلب التفويض (prompt)، واحتفظ بالقواعد العامة والدائمة فقط داخل ملف
AGENTS.md. وتوفير القواعد وتحديدها أفضل بكثير من كتابة نصوص طويلة بلا فائدة.
وهناك عادة عملية متميزة تنصح بها الجهة الرسمية ويفضل اتباعها: عندما يكرر Codex الوقوع في نفس الخطأ للمرة الثانية، اطلب منه مراجعة الأمر وكتابة الدرس المستفاد كقاعدة جديدة داخل ملف AGENTS.md. لتتطور إرشادات ملف التوجيهات بناءً على أخطاء عمل حقيقية، وليس بناءً على افتراضات نظرية تضعها مسبقًا.
💡 الخلاصة في جملة واحدة: احفظ القواعد الدائمة والعامة في ملف
AGENTS.mdواجعله قصيرًا ومباشرًا وحقيقيًا، وتجنب حشوه بالتعليمات المؤقتة أو النصوص الطويلة غير المفيدة.
03 صياغة الطلبات ليست بالصدفة: الهدف + السياق + القيود + القبول، تعبئة الخانات الأربع
لماذا نقوم بذلك. تحدثنا في المقالة السابقة عن صياغة الطلبات، ونضيف هنا هيكلاً واضحًا وصالحًا للتطبيق المباشر. يتمتع Codex اليوم بقدرات قوية ويمكنه تقديم نتائج مقبولة حتى مع الطلبات المصاغة بشكل عشوائي؛ ولكن في المشاريع الكبيرة أو المهام الحساسة، يؤدي غموض الطلب لتخمين الحلول من طرفه، مما يضطرك لإعادة العمل.
تتكون الوصفة الرسمية للـ «طلب المتميز» من أربعة عناصر، وأتعامل معها كخانات يجب تعبئتها:
| العنصر | ماذا يوضح للنموذج | المشكلة الناتجة عن إهماله |
|---|---|---|
| الهدف (Goal) | ما المطلوب تعديله أو بناؤه تحديدًا | يتشتت النموذج ويقوم بأعمال وتعديلات غير مطلوبة |
| السياق (Context) | ما هي الملفات أو السجلات أو الأمثلة ذات الصلة (استخدم @ لتحديد الملفات) | يبحث بشكل عشوائي في المجلدات ويستغرق وقتًا طويلاً |
| القيود (Constraints) | ما هي معايير التصميم أو البنية أو المتطلبات الأمنية المطلوبة | يكتب الكود بأسلوبه الخاص وتضيع المعايير المتبعة |
| معايير القبول (Done when) | ما هي الشروط التي تعني انتهاء العمل بنجاح | يكتفي بإنشاء كود «يبدو قابلاً للتشغيل» ويترك لك تتبع الأخطاء |
كيفية التطبيق. لا داعي لكتابة شروط قانونية معقدة في كل طلب. ولكن للمهام المعقدة أو التي لا تريد تكرار تشغيلها، مر على هذه الخانات الأربع في ذهنك (أو اكتبها مباشرة في طلبك): ما المطلوب عمله، وأين توجد الملفات المعنية، وما المحاذير التي يجب مراعاتها، ومتى يعتبر العمل ناجحًا ومكتملًا.
تشبيه: تشبه هذه الأجزاء الأربعة تفاصيل تعليمات العمل لعمال البناء. لا يمكنك الاكتفاء بمطالبتهم بـ «تعديل المطبخ ليصبح أفضل» وتركهم للعمل — بل يجب تحديد التصميم المطلوب (الهدف)، ومخططات الكهرباء والمياه (السياق)، ومنع الاقتراب من الجدران الخرسانية الحاملة (القيود)، واجتياز فحص تشغيل المياه والإضاءة وسلامة الخزائن (معايير القبول). فكلما كانت التعليمات واضحة، انخفضت معدلات إعادة العمل.
العنصر الأكثر تعرضًا للإهمال لدي هو معايير القبول. في السابق طالبت Codex بتعديل فحص صحة مدخلات نموذج، واكتفيت بقول «أضف فحصًا لصيغة رقم الهاتف»، ولم أذكر «تأكد من عدم تعطل فحص البريد الإلكتروني الحالي ونجاح الاختبارات ذات الصلة». فقام بإضافة فحص رقم الهاتف بنجاح، وتسبب التعديل في تعطيل فحص البريد الإلكتروني بالخطأ، ولم أكتشف المشكلة إلا عند تشغيل الاختبارات قبل الدمج. ومنذ ذلك الحين، أحرص على كتابة خانة «Done when» دائمًا.
💡 الخلاصة في جملة واحدة: تجنب الكتابة العشوائية للطلبات، واتبع صيغة «الهدف + السياق + القيود + القبول» لتعبئة الخانات، ولا تهمل تحديد معايير القبول.
04 إعداد الخطة أولاً للمهام المعقدة قبل التنفيذ
لماذا نقوم بذلك. مع زيادة تعقيد أو غموض المهمة، يؤدي مطالبته بكتابة الكود مباشرة لتخمين نيتك أثناء الكتابة، مما قد يوجهه للمسار الخاطئ ولن تكتشف ذلك إلا في مراحل متأخرة. ومطالبته بتقديم خطة عمل أولاً يمنحك فرصة مجانية وسهلة لـ «تصحيح المسار» قبل كتابة الكود.
تشبيه: يشبه هذا مراجعة المخططات الهندسية قبل البناء. لا يمكن مطالبة عمال البناء برص الطوب دون وجود مخطط — وتعديل الجدار بعد بنائه خاطئًا مكلف وصعب للغاية. الخطة هي المخطط الهندسي، تتكون من أسطر بسيطة، وتكلفتها لا تذكر مقارنة بإعادة كتابة كود برمجى كامل.
كيفية التطبيق. توفر التوجيهات الرسمية عدة طرق، ونرتبها حسب سهولة البدء:
- استخدام وضع الخطة Plan mode (موصى به): اكتب أمر
/planداخل واجهة CLI، أو استخدم الاختصار Shift+Tab للتبديل. سيقوم أولاً بجمع السياق وطرح بعض الأسئلة للتوضيح وتقديم خطة عمل واضحة، ويبدأ التنفيذ بمجرد موافقتك. - توجيهه لطرح الأسئلة ومناقشتك: إذا كنت غير متأكد من التفاصيل بنفسك، وجهه بـ «لا تبدأ كتابة الكود الآن، ناقشني واطرح أسئلة لتوضيح هذه الفكرة الغامضة وتحويلها لسيناريو عمل محدد».
- استخدام قالب
PLANS.md: وهي طريقة متقدمة لتنظيم المهام الطويلة متعددة الخطوات بناءً على قالب خطة تنفيذ محدد (راجع شروحات execution plans الرسمية).
مثال خاطئ. تصنف التوجيهات الرسمية «تجاوز خطوة التخطيط للمهام المعقدة متعددة الخطوات» ضمن الأخطاء الشائعة، ومررت بهذه التجربة شخصيًا. طلبت من Codex سابقًا مساعدتي في تحويل وحدة برمجية من نظام استدعاء الدوال التقليدي (callback) إلى نظام async/await، وبحثًا عن السرعة لم أطلب منه تقديم خطة عمل ووجهته بـ «ابدأ التعديل مباشرة». وقام بالتعديل وتعديل المنطق البرمجي، وقام في طريقه بـ «تحسين» منطق معالجة الأخطاء العام دون طلب مني، وتداخلت التعديلات وأصبحت مراجعة الفروقات (diff) صعبة ومعقدة للغاية، واضطررت لتشغيل أمر git reset والبدء من جديد — وقمت في المرة الثانية بتفعيل وضع الخطة /plan أولاً، وتحديد «الملفات التي سيتم تعديلها والتعديلات المطلوبة لكل ملف والمحاذير الأمنية»، واجتاز العمل بنجاح من أول مرة بعد تأكيد الخطة.
💡 الخلاصة في جملة واحدة: كلما زادت صعوبة أو غموض المهمة، تبرز أهمية تشغيل وضع الخطة
/planأولاً لتأكيد المسار، قبل مطالبته بكتابة الكود.
05 مستويات الصلاحيات: التقييد افتراضيًا والفتح التدريجي حسب الحالات
لماذا نقوم بذلك. يحتوي Codex على نظام sandbox مدمج على مستوى نظام التشغيل، ويتحكم فيه مفتاحان أساسيان: وضع الموافقة (approval mode) للتحكم في الحاجة لطلب الإذن قبل تشغيل أي أمر، ووضع الـ sandbox (sandbox mode) للتحكم في صلاحيات القراءة والكتابة والوصول للمجلدات والشبكة. وفتح الصلاحيات بالكامل من البداية يشبه تسليم عجلة القيادة ودواسة الوقود لسائق جديد لم تتعرف على مهاراته بعد.
تشبيه: يشبه هذا منح الصلاحيات للموظف الجديد. تقتصر صلاحياته في الأيام الأولى على قراءة الكود وتشغيل الاختبارات المحلية؛ وبعد زيادة الثقة والاطمئنان لعمله، تبدأ في فتح صلاحيات تعديل الملفات والوصول لقواعد البيانات تدريجيًا. ولا يتم تسليم مفاتيح خوادم الإنتاج للموظف الجديد من اليوم الأول.
كيفية التطبيق. النصيحة الرسمية مباشرة للغاية:
- ابدأ العمل بالاعتماد على المستويات الافتراضية المقيدة للصلاحيات والموافقة عند البدء كشخص مبتدئ.
- بعد فهم أسلوب العمل والتأكد من سلامة النتائج، يمكنك فتح الصلاحيات تدريجيًا لمستودعات معينة أو حالات خاصة لتسهيل العمل، وتجنب فتح الصلاحيات بالكامل افتراضيًا.
| السيناريو | المستوى الموصى به | السبب |
|---|---|---|
| في البداية / مع المشاريع الجديدة | الإعدادات الافتراضية (طلب الإذن قبل التنفيذ، sandbox مقيد) | فحص ومراجعة الأوامر والعمليات قبل السماح بالتنفيذ للحفاظ على الأمان |
| في مستودعاتك الموثوقة والمهام المتكررة | تقليل متطلبات طلب الموافقة | للحد من كثرة ظهور نوافذ الموافقة وتسهيل العمل |
| عند تشغيل سكريبتات أو كود خارجي غير موثوق | التقييد لأقصى درجة | لمنع تشغيل أي أوامر أو عمليات غير متوقعة على جهازك |
تصنف المستندات الرسمية «منح Codex صلاحيات كاملة للجهاز قبل فهم أسلوب وسير العمل» كخطأ شائع. ولم تكن تجربتي السابقة كارثية ولكنها كانت درسًا هامًا: حيث قمت بتخفيف سياسة الموافقة لتفادي النوافذ المتكررة، وقام أثناء إعادة هيكلة كود بتشغيل أمر مسح وحذف بعض الملفات المؤقتة التي كنت أحتاجها لاحقًا — لم تكن كارثة كبرى ولكنها نبهتني لضرورة الحذر. توفير ثواني الموافقة لا يساوي المخاطرة الأمنية.
💡 الخلاصة في جملة واحدة: اعتمد على التقييد الأمني الصارم افتراضيًا، وراجع العمليات قبل السماح بها؛ وافتح الصلاحيات تدريجيًا للحالات الموثوقة وتجنب الفتح الكامل افتراضيًا.
06 دعه يتحقق بنفسه: الاختبار والفحص والمراجعة، ولا تدعه يكتفي بـ «كتابة الكود»
لماذا نقوم بذلك. تعتبر هذه النصيحة هي الأكثر أهمية وفائدة. تجنب مطالبة Codex بكتابة الكود والوقوف عند ذلك — بل وجهه لكتابة الاختبارات اللازمة وتشغيل الفحوصات ومراجعة الكود قبل تسليم المهمة. ويغنيك هذا عن جولات الفحص البشري المتكررة «يكتب الكود ← تقوم بالاختبار وتكتشف خطأ ← توجهه للإصلاح ← يعيد التعديل».
ولكن هناك شرط هام: يجب أن يعرف كيف يبدو الحل «الصحيح». وتأتي هذه المعايير إما من طلبك أو من قواعد ملف AGENTS.md (والتي ترتبط بالقسم 02).
كيفية التطبيق. تشمل عمليات «التحقق الذاتي والتحقق المغلق» التي يقوم بها Codex الإجراءات التالية، ويمكنك إضافتها مباشرة لشروط القبول:
- كتابة أو تحديث الاختبارات للتعديلات الجديدة
- تشغيل مجموعات الاختبارات المعنية والتأكد من نجاحها
- تشغيل أدوات الفحص (lint) والتنسيق وتدقيق الأنواع
- التأكد من مطابقة النتائج النهائية لمتطلبات طلبك
- مراجعة الفروقات (diff) بنفسه للبحث عن أخطاء أو تراجعات في الأداء أو كود خطر
ويمثل أمر /review أداة متميزة في هذا الجانب: حيث يقوم بمراجعة وتدقيق التعديلات ومقارنتها مع الفرع الرئيسي بأسلوب مراجعة طلبات السحب (PR)، أو مراجعة التغييرات غير الملتزم بها، أو المراجعة وفقًا لقواعد مخصصة تحددها له. وإذا كان مشروعك يحتوي على ملف قواعد المراجعة code_review.md وتمت الإشارة إليه في AGENTS.md، فسيقوم Codex بمراجعة وتدقيق الكود بالاعتماد على تلك القواعد — وهو أمر متميز للحفاظ على معايير كتابة موحدة عند عمل عدة مطورين معًا.
مثال خاطئ. تصنف المستندات الرسمية «منع الوكيل من التحقق من نتائج عمله بنفسه» (بسبب عدم توضيح كيفية تشغيل البناء والاختبارات له) كخطأ شائع. ومررت بهذه المشكلة سابقًا: طلبت منه تعديل دالة معالجة بيانات وتكاسلت عن مطالبته بتشغيل الاختبارات، وأكد لي أن «العمل مكتمل والمنطق سليم» ووافقت على دمج التعديلات. وانهار الكود عند التشغيل مع حالات حدية في الإنتاج — ولم يكن بمقدوره اكتشاف الخطأ لعدم مطالبته بتشغيل الاختبارات. ومنذ ذلك الوقت اعتمدت قاعدة: إضافة عبارة «شغل أمر الاختبار <测试命令> بعد التعديل، وتأكد من نجاح جميع الحالات قبل إخطاري» في نهاية كل طلب. عبارة بسيطة تحميك من أغلب المشاكل وإعادات العمل.
💡 الخلاصة في جملة واحدة: وجه Codex لإجراء الاختبارات والفحص والمراجعة بنفسه قبل تسليم العمل، مع تحديد معايير «العمل الصحيح» له في الطلب أو في ملف
AGENTS.md.
07 المهام الخاصة ببيئات الإنتاج: الحصول على الأدلة والتحقق أولاً قبل الإصلاح
لماذا نقوم بذلك. يمكن الاعتماد على الاختبارات الآلية للتحقق من المهام البرمجية المحلية. ولكن عند معالجة المشاكل في بيئات الإنتاج (live environments)، يجب الإجابة أولاً على أسئلة هامة: ما هي الأعراض الحقيقية التي يواجهها المستخدم، وكيف يمكن إعادة إنتاجها، وما هي السجلات المعنية بالخطأ في هذا التوقيت، وهل تم التحقق من عمل الميزة بعد التعديل من خلال نفس مسار حركة المستخدم.
أعتمد الآن على قاعدة عمل للمشاكل البرمجية في الإنتاج: البحث عن الأدلة والتحقق أولاً، ثم تقييم المشكلة، ثم البدء في الإصلاح. سيقوم Codex بتتبع المشكلة في الكود، ولكن مطالبته بـ «أصلح هذا الخطأ فورًا» ستجعله يفترض أن أقرب سيناريو يراه هو سبب المشكلة، ويعتبر اجتياز الاختبارات المحلية دليلاً على الإصلاح. وفي مهام الإنتاج، كلا التقييمين غير كافٍ.
كيفية التطبيق. وجهه أولاً لجمع الأدلة وتجنب تعديل الكود مباشرة. ويمكن صياغة الطلب كالتالي:
先不要改代码。请按证据链排查这个线上问题：
1. 复现用户路径，记录请求方式、状态码、关键响应摘要和时间。
2. 查对应时间段的应用日志，只摘出相关错误行。
3. 找到涉及的配置、路由、任务或数据表，但不要修改生产状态。
4. 给出「已验证事实 / 待确认假设 / 下一步验证」三段结论。
5. 输出时脱敏，隐藏 token、私有访问链接、邮箱、手机号、订单号和内部地址。(Note: we preserve the Chinese prompt here because it is in a code block).
توجه هذه الصياغة Codex للتركيز على «إثبات المشكلة» أولاً وتجنب التعديل العشوائي. ويجب أن ترتبط استنتاجاته بالأدلة المتاحة: أي الطلبات فشل، وأي أسطر السجلات تحتوي على الخطأ، وأي ملفات التكوين تتدخل في هذا المسار، وما هي الخطوة القادمة لإثبات أو نفي هذه الافتراضات.
وأحرص على إضافة قواعد واضحة في ملف AGENTS.md لمعالجة هذه الحالات:
## 线上问题处理
- 先复现原问题，记录状态码、关键响应摘要、日志时间和验证路径。
- 未经确认，不要改生产数据、权限、可见性、计费、通知或工单状态。
- 输出内容必须脱敏，不要贴 token、用户信息、私有链接、密钥、完整 IP 或订单号。
- 修复后必须用原用户路径复查；本地测试通过不等于线上恢复。
- 如果不能复查，说明缺哪条证据、为什么缺、下一步谁能补。(Note: we preserve the Chinese rules because they are in a code block).
تمنح هذه القواعد التوجيهات الأمنية اللازمة لـ Codex. فعندما يقرأ «يجب إعادة الفحص باستخدام نفس مسار حركة المستخدم بعد الإصلاح»، لن يكتفي بتشغيل اختبار محلي وإعلان نجاح العمل؛ وعندما يقرأ «تجنب تعديل بيانات الإنتاج دون تأكيد»، سيتوقف لطلب موافقتك الصريحة عند محاولة تشغيل عمليات تؤثر على حالة المستخدمين.
إلغاء حساسية البيانات مع الاحتفاظ بالمعلومات المفيدة للتحليل. إهمال كتابة تفاصيل السجل وحذف كل المعلومات تحت مسمى إلغاء الحساسية يحرم المطورين من تتبع الخطأ لاحقًا. احرص على إخفاء القيم الحساسة مع الاحتفاظ بالهيكل العام للمدخلات:
| البيانات الأصلية | طريقة الكتابة بعد إلغاء الحساسية |
|---|---|
https://example.com/private/path?token=secret_value | https://example.com/private/path?token=<token> |
user@example.com | <user-email> |
order_20260201_123456 | <order-id> |
Authorization: Bearer ... | Authorization: Bearer <redacted> |
2026-02-01 14:03:22 status=500 | الاحتفاظ بالتوقيت وحالة الطلب |
يمكن الاحتفاظ بالتوقيت، وحالة الطلب، ونوع الخطأ، وهيكل المسار (route)؛ ويجب إخفاء البيانات الشخصية للمستخدمين، وتفاصيل الحسابات، والمفاتيح السرية، والعناوين الداخلية. لتسهيل تتبع المشكلة دون كتابة معلومات حساسة في طلبات السحب (PR) أو سجلات المحادثات العامة.
كيفية التحقق. يجب أن ترتبط معايير قبول مهام الإنتاج بالمسارات الحقيقية. فإذا تعطلت واجهة برمجية، أعد تشغيل نفس الواجهة وسجل حالة الطلب الجديدة والردود؛ وإذا تعطلت صفحة ويب، تتبع الخطوات عبر المتصفح للتأكد؛ وإذا فشلت المهام المجدولة، فافحص سجلات التشغيل القادمة والنتائج. وفي حال غياب الصلاحيات اللازمة للتحقق في بيئات الإنتاج، تجنب كتابة جمل عامة مثل «تعذر التحقق»، ووضح التفاصيل بدقة: غياب صلاحية الوصول للإنتاج، غياب حساب الاختبار المخصص، غياب منافذ الاتصال الخارجية، أو الحاجة لتأكيد المستخدم النهائي.
💡 الخلاصة في جملة واحدة: تجنب توجيه Codex لتخمين المشاكل في بيئات الإنتاج، واطلب منه جمع الأدلة أولاً؛ وأعد التحقق من الإصلاح باستخدام نفس مسارات المستخدمين، مع إخفاء البيانات الحساسة والاحتفاظ بالتوقيت وحالات الطلبات والأخطاء للتحليل.
08 تفويض المهام الكبيرة للوكلاء الفرعيين، وتخصيص جلسة عمل واحدة لكل مهمة
لماذا نقوم بذلك. لا تمثل الجلسة (session) مجرد سجل للمحادثة، بل هي خط سياق يتراكم محتواه مع الوقت. وزيادة طول الجلسة وتداخل المهام بداخلها يؤدي لتراجع جودة مخرجات الذكاء الاصطناعي. لذا تؤثر طريقة إدارتك للجلسات بشكل مباشر على جودة النتائج.
تشبيه: يشبه هذا تنظيم مكتب العمل الخاص بك. إذا تداخلت ملفات ثلاثة مشاريع مختلفة على نفس المكتب، فستجد صعوبة وتستغرق وقتًا أطول في مراجعة وتحديد المستندات؛ بينما يؤدي تنظيم المكتب وتخصيصه للمهمة الحالية فقط لأعلى كفاءة. وتمثل الجلسة مكتب العمل الخاص بـ Codex.
كيفية التطبيق (قاعدتان أساسيتان).
أولاً: تخصيص الجلسة لمهمة واحدة متصلة. تشير التوجيهات الرسمية إلى ضرورة البقاء في نفس الجلسة طالما كان العمل يدور حول نفس المشكلة — للحفاظ على تسلسل الاستدلال البرمجي متصلاً. واستخدام أمر /fork لتوليد جلسة جديدة فقط عند تفرع العمل لمهام جانبية. وبتعبير آخر، قم بإنشاء الجلسات بناءً على المهام وليس بناءً على المشاريع — ويتمثل الخطأ الشائع في «الاعتماد على جلسة عمل واحدة للمشروع بأكمله من البداية للنهاية»، مما يؤدي لتضخم حجم السياق وتراجع النتائج.
ثانياً: تفويض المهام الجانبية واضحة الحدود للوكلاء الفرعيين (subagents). ركز الجلسة الرئيسية على معالجة المنطق الجوهري للمهمة، وقم بتفويض المهام الجانبية — مثل استكشاف الكود، أو كتابة الاختبارات، أو تصنيف الأخطاء — لوكلاء فرعيين لإنجازها بشكل مستقل، لتفادي تشتيت انتباه الجلسة الرئيسية.
الأوامر العملية لإدارة الجلسات (تعتمد على ما يدعمه أمر codex --help محليًا):
/resumeلاستكمال حوار جلسة سابقة تم حفظها/forkلبدء جلسة جديدة متفرعة مع الاحتفاظ بسجل الجلسة الأصلية/compactلضغط السياق وتلخيصه عند تضخم الجلسة (يقوم Codex بالضغط تلقائيًا أيضًا)/statusلمراجعة حالة الجلسة الحالية وحجم السياق المتبقي
عادتهم الحالية هي «تخصيص جلسة لكل مهمة»، وأرشفة الجلسة بمجرد انتهاء العمل. ورغم بساطة هذا الإجراء، لاحظت أن ردود Codex أصبحت أكثر دقة ولم تعد تتداخل مع متطلبات سابقة — ففي السابق كان يستحضر تفاصيل طلبات قمت بها قبل أيام ويقحمها في منطق المهمة الحالية بالخطأ.
💡 الخلاصة في جملة واحدة: خصص جلسة عمل لكل مهمة، وفوض المهام الجانبية للوكلاء الفرعيين، وتجنب تضخم السياق وتداخل المحادثات لحماية جودة النتائج.
09 دليل البدء السريع: جدول «أخطاء شائعة ❌ / الممارسة الصحيحة ✅»
تلخص المستندات الرسمية في نهايتها الأخطاء الشائعة المرتكبة. وقمت بصياغتها في جدول مقارنة لتسهيل المراجعة والتحقق الذاتي — وإذا لاحظت أن عملك يتطابق مع أي بند في الجانب الأيسر، فقم بتعديله باتباع التوجيه المقابل في الجانب الأيمن.
| ❌ أخطاء شائعة | ✅ الممارسة الصحيحة |
|---|---|
| كتابة القواعد العامة والمستقرة داخل طلب التفويض (prompt) | نقل القواعد المستقرة لملف AGENTS.md أو المهارات (skills)، واقتصار الطلب على متطلبات المهمة الحالية |
| إهمال توضيح كيفية تشغيل البناء والاختبارات له | كتابة أوامر التشغيل والاختبار في ملف AGENTS.md لتمكينه من التحقق من عمله وتصحيح الأخطاء |
| البدء في كتابة الكود مباشرة للمهام المعقدة متعددة الخطوات | تفعيل وضع الخطة /plan أولاً لتحديد مسار العمل وتأكيده قبل كتابة الكود |
| منح صلاحيات كاملة للجهاز قبل فهم أسلوب العمل | التقييد افتراضيًا، وفتح الصلاحيات تدريجيًا للحالات الموثوقة |
| الاعتماد على جلسة عمل واحدة للمشروع بالكامل | تخصيص جلسة لكل مهمة، واستخدام /fork عند تفرع العمل |
| تعديل نفس الملفات بالتوازي في جلسات متعددة دون عزل | استخدام git worktree لتخصيص بيئة عمل مستقلة لكل جلسة لتفادي تداخل التعديلات |
| التسرع في أتمتة المهام غير المستقرة | تشغيل المهام يدويًا والتأكد من سلامتها أولاً قبل تحويلها لمهارات أو أتمتتها |
| مراقبة خطواته خطوة بخطوة وإعاقة عملك | تركه يعمل بالتوازي في الخلفية والاستمرار في مهامك الخاصة |
| البدء في إصلاح مشاكل الإنتاج دون جمع الأدلة | تسجيل الأعراض وحالات الطلبات وتوقيت الأخطاء وإعادة إنتاج المشكلة أولاً |
| إعلان الإصلاح بمجرد نجاح الاختبارات المحلية | التحقق من الإصلاح في الإنتاج باستخدام نفس مسارات المستخدمين ومراقبة السجلات |
| كتابة السجلات والمفاتيح وبيانات المستخدمين كما هي في التوجيهات العامة | إلغاء حساسية البيانات الحساسة مع الاحتفاظ بالتوقيت وحالات الطلبات والأخطاء للتحليل |
كيفية الاستخدام. تجنب قراءة هذا الجدول لمرة واحدة فقط. وأنصحك بـ: الرجوع للمقارنات الموضحة في هذا الجدول عند شعور ببطء وتكرار إعادات العمل مع Codex، وستكتشف الموضع الذي يتطلب تعديل أسلوب عملك. فكل الأخطاء الموضحة في الجانب الأيسر قد وقعت فيها شخصيًا وتكبدت عناءها قبل استيعاب الممارسة الصحيحة.
💡 الخلاصة في جملة واحدة: اعتمد على هذا الجدول للتحقق الذاتي، وقم بتعديل الممارسات الخاطئة بالتبعية، وستجد فائدته أكبر من حفظ النصائح العامة.
10 ملخص
لم تعرض هذه المقالة نصائح بديهية، بل ركزت على ثماني ممارسات عملية أثبتت فاعليتها لتغيير أسلوب العمل مع Codex:
- طريقة التفكير: التعامل مع Codex كزميل عمل يتم توجيهه وتدريبه باستمرار، وهو أساس نجاح العمل.
- ملف
AGENTS.md: حفظ القواعد العامة والمستقرة فيه، والحفاظ عليه قصيرًا ومباشرًا ودقيقًا. - صياغة الطلب: الاعتماد على صيغة «الهدف + السياق + القيود + القبول» لتعبئة التفاصيل، ولا تهمل شروط القبول.
- التخطيط أولاً: تفعيل وضع الخطة
/planللمهام المعقدة لتأكيد المسار البرمجي قبل كتابة الكود. - تحديد الصلاحيات: التقييد افتراضيًا لحماية الأمان، والسماح بالصلاحيات تدريجيًا للحالات الموثوقة.
- التحقق الذاتي: مطالبته بالاختبار والفحص والمراجعة للمخرجات بنفسه، وتوضيح معايير العمل الناجح له.
- مشاكل الإنتاج: التركيز على جمع الأدلة وإعادة إنتاج المشكلة وإلغاء حساسية البيانات والتحقق من الإصلاح في الإنتاج.
- إدارة الجلسات: تخصيص جلسة عمل لكل مهمة لتفادي تداخل المحادثات وتضخم السياق، وتفويض المهام للوكلاء الفرعيين.
ينبغي عليك الآن أن تكون قادرًا على: مراجعة خطواتك عند بدء أي مهمة مع Codex — هل تتطلب المهمة وضع خطة عمل أولاً، وهل تم تحديد معايير القبول بوضوح، وهل تعكس إرشادات AGENTS.md القواعد المطلوبة، وهل تم توجيهه للاختبار الذاتي، وما هو مستوى الصلاحيات المناسب، وهل نحتاج لجمع أدلة للإنتاج أولاً. وبتحويل هذه الخطوات لعادات عمل يومية، ستنتقلcollaborative عملك مع Codex من مرحلة «توقع النتائج بالصدفة» إلى «العمل الممنهج المنظم».
المقالة التالية 〔37 تتبع المشاكل الشائعة وإصلاحها〕 تتناول الجانب الأكثر عملية: فمهما كنت حريصًا في اتباع القواعد، فسيواجه Codex بعض المشاكل والأخطاء أثناء العمل — كفشل الأوامر، وتخريب الكود، ومشاكل الاتصال، والتصرفات الغريبة للنموذج. حدوث المشاكل ليس كارثة، والكارثة هي عدم معرفة من أين تبدأ الفحص والتشخيص. فكر في هذا السؤال: مع اتباعنا لنصائح «التخطيط أولاً، والاختبار الذاتي، والعمل بخطوات مصغرة» لمنع المشاكل؛ ما هو أول موضع ستفحصه عند حدوث خطأ فعلي؟ سنناقش ترتيب خطوات التشخيص وال排查 في المقالة القادمة.