التكامل مع Git و GitHub: توظيف Codex كمراجع للـ PR

📚 التنقل في السلسلة: المقال السابق [25 · فروع العمل المتوازية (Worktrees)] علمك كيفية استخدام git worktree لفتح "مسارات عمل متوازية" لـ Codex لمعالجة مهام متعددة في نفس الوقت ودون تداخل. هذا المقال ينقل ساحة العمل من سطر الأوامر المحلي لـ مستودع GitHub: لنتعلم كيفية إشراك Codex في مراجعة طلبات السحب (Pull Request)، ليفحص الأكواد تلقائياً، ويرصد الأخطاء بناءً على معاييرك، ويدفع الإصلاحات للفرع مباشرة. المقال التالي [27 · التشغيل الآلي والتكامل المستمر (CI/CD)] سينقل هذه الممارسات لخطوات البناء المؤتمتة (CI/CD) للعمل بشكل مستقل تماماً.

نبدأ بسيناريو يتكرر يومياً في فرق المطورين. يستغرق طلب السحب (PR) منذ فتحه وحتى دمجه وقتاً طويلاً يضيع معظمه في "انتظار قيام شخص ما بالمراجعة" - فمع صغر حجم الفريق وانشغال المراجعين، يظل طلبك معلقاً ليوم كامل أو أكثر كأمر معتاد.

وعند بدء المراجعة الفعلية، ينصب تركيز المطورين غالباً على الملاحظات التجميلية مثل "اسم هذا المتغير غير دقيق" أو "توجد مسافة زائدة هنا"؛ بينما يتم إغفال الأخطاء الجسيمة والمدمرة - مثل مشاكل التزامن والتسابق (race condition)، غياب تراخيص الأمان في الواجهات، أو كتابة بيانات المستخدمين الحساسة في السجلات - نظراً للتعب وتشتت الذهن بعد قراءة بضعة ملفات، وهي الملاحظات الأسهل في السقوط.

تم تصميم تكامل Codex مع GitHub لمعالجة هذا الخلل: فبمجرد كتابة إشارة بسيطة @codex review في تعليقات PR، يتولى المساعد فحص التعديلات ومقارنتها بدقة مع المعايير الخاصة بالشركة، ويرصد المشاكل الجسيمة ويعلق عليها مباشرة. ويوفر عليك عناء فتح التطبيقات، ولا يتدخل في قرار الدمج النهائي - فالمساعد يتولى الفحص وكتابة الملاحظات، وأنت تتولى اتخاذ قرار القبول والدمج يدوياً، وهي حدود الصلاحيات والأمان التي التزمنا بها منذ المقال 15.

بقراءة هذا المقال، ستحصل على:

• كيفية استدعاء المراجعة يدوياً بكتابة @codex review في تعليقات PR، وشكل الملاحظات ومستوى الأخطاء التي يرصدها (مستوى P0 و P1 بالتحديد وفقاً للوثائق)
• كيفية تمكين "المراجعة التلقائية" - ليعمل الفحص التلقائي بمجرد فتح أي PR جديد ودون حاجة لطلب يدوي
• تخصيص شروط وقواعد الفحص بكتابة قسم Review guidelines في ملف AGENTS.md للمشروع (مثل منع تسجيل بيانات PII، وإجبار تراخيص الأمان للواجهات)
• استخدام أمر @codex fix للطلب منه إصلاح المشاكل المكتشفة ورفع التعديلات للفرع مباشرة، وحدود الأمان والصلاحيات المطلوبة لذلك
• استخدام الفحص المحلي /review: لإجراء فحص الكود ذاتياً من الطرفية قبل رفع التعديلات وفتح PR، دون إجراء أي تعديل للملفات
• القاعدة الذهبية للعمل: ما هي المهام البرمجية التي نسندها للمساعد بأمان، وما هي القرارات الحساسة التي نلتزم بتنفيذها يدوياً

⚠️ تذكر أن مراجعات GitHub السحابية (التفعيل عبر التعليقات أو المراجعة التلقائية) تعتمد على بيئة Codex السحابية (Codex cloud)، وتتطلب اشتراكاً مدفوعاً وتفعيل ربط المستودع؛ بينما يعمل الفحص المحلي /review محلياً بالكامل ولا يتطلب بيئة سحابية. وسنشرح المسارين بالتفصيل لتفادي اللبس.

---

01 طريقتان للعمل: المساعد في سحابة GitHub مقابل المساعد في طرفيتك المحلية

قبل البدء، نوضح الفارق الأساسي لتلافي اللبس: تتوفر ميزتان مختلفتان تماماً لفحص الكود ومراجعة الأخطاء تختلفان في مكان التشغيل والصلاحيات.

تشبيه: المعلم الموثوق، الذي يمكنه تصحيح كراسة واجباتك بعد تسليمها، أو الجلوس بجانبك ومراجعة الحل أثناء الكتابة. الأول يمثل "التصحيح بعد انتهاء العمل وتسليم الورقة"؛ والثاني يمثل "التصحيح المباشر أثناء الحل". يقوم المعلم بالعمليتين، ولكن سياق وصلاحيات وأوقات العمل تختلف تماماً.

وينطبق نفس الأمر على Codex كالتالي:

المسار الأول: التفعيل السحابي عبر GitHub (Cloud). تكتب تعليقاً باسم @codex review في واجهة PR على موقع GitHub، ليقوم Codex في السحابة بتشغيل مهمة فحص لقراءة التعديلات (diff) وكتابة ملاحظات المراجعة مباشرة على الأسطر في GitHub. وتتم العملية بالكامل على السحابة ودون استهلاك لموارد جهازك (وهو ما شرحناه في المقال 10 لـ Codex cloud). متطلبات التشغيل: ربط المستودع بالخدمة وتفعيل خيار Code review في الإعدادات.

المسار الثاني: الفحص المحلي /review (CLI). تكتب الأمر المائل /review في محادثة Codex على طرفيتك المحلية، ليقوم المساعد على جهازك بفحص التعديلات المحددة (سواء كانت تعديلات لم ترفع بعد، أو الفروق بين الفروع، أو تعديل محدد)، ويعرض الملاحظات في واجهة الطرفية. وهي عملية للقراءة فقط ويُمنع إجراء أي تعديل على ملفاتك. وتعمل محلياً بالكامل دون متطلبات ربط سحابية.

وجه المقارنة	الفحص السحابي عبر تعليقات GitHub (@codex review)	الفحص المحلي عبر الطرفية (/review)
مكان الاستدعاء	في تعليقات PR على موقع GitHub	في جلسة محادثة Codex على الطرفية
مكان تشغيل المهمة	بيئة Codex السحابية (Codex cloud)	محلياً على جهازك
الملفات المستهدفة	التعديلات الخاصة بطلب السحب الحالي (diff)	التعديلات المحلية (غير المرفوعة، فروق الفروع، أو commit محدد)
مكان عرض النتائج	تعليقات مراجعة مكتوبة على أسطر الكود في PR	معروضة في قائمة الملاحظات بالطرفية
متطلبات العمل	ربط المستودع وتفعيل خيار Code review السحابي	تعمل مباشرة دون إعدادات ربط
تعديل الكود	لا يعدل (إلا إذا طلبت منه الإصلاح بأمر @codex fix لاحقاً)	للقراءة فقط وتمنع التعديل تماماً

يركز هذا المقال بالأساس على المسار الأول (تكامل GitHub السحابي) - نظراً لكونه محور التكامل الرسمي للمشاريع المشتركة؛ ونوضح المسار الثاني /review في القسم 06 كخطوة فحص ذاتية وهامة تسبق رفع الأكواد.

💡 ملخص في جملة واحدة: ينقسم فحص الكود لمسارين - سحابي عبر تعليقات GitHub بنص @codex review (يتطلب ربط المستودع والاشتراك السحابي لتسجيل الملاحظات في PR)، ومحلي عبر أمر /review في الطرفية (يعمل للقراءة فقط على جهازك). ويركز المقال على المسار السحابي، ويمثل المسار المحلي خطوة فحص ذاتية.

---

02 استخدام أمر @codex review في تعليقات PR

تتمثل الطريقة الأساسية للتشغيل في: كتابة تعليق @codex review في صندوق المحادثة لطلب السحب (PR) وإرساله.

لماذا يفضل الاعتماد على المساعد في المراجعة؟ لأن "المراجعة الدقيقة لطلب سحب طويل" هي مهمة تستهلك طاقة ذهنية كبيرة ويسهل تأجيلها من قبل المطورين - مما يبقي طلبات السحب معلقة لفترات طويلة؛ وعند مراجعتها يسهل سقوط الأخطاء الجسيمة بسبب الإرهاق وتشتت الانتباه. وإسناد هذه المهام المرهقة لمساعد لا يتعب يساعد في تنقية الكود ورصد الأخطاء مبكراً.

تشبيه: المحرر المتخصص برصد الأخطاء الفادحة قبل طباعة الكتاب. قراءة كتابك وتدقيقه بنفسك لعدة مرات لا تحميك من سقوط الأخطاء - لأن عقلك يقوم بتمرير النصوص بناءً على المعنى الذي أردت كتابته. والحل هو إعطاء المسودة لمحرر متخصص وظيفته البحث عن الأخطاء الجسيمة فقط - مثل التناقضات المنطقية والتواريخ الخاطئة. ويمثل Codex هذا المحرر لـ PRs: فهو لا يمتدح جودة صياغة الكود، بل يبحث عن الثغرات التي تسبب توقف وأعطال النظام.

توجه لتعليقات طلب السحب في GitHub، واكتب التالي:

@codex review

وبعد إرسال التعليق، تسير الخطوات الفنية كالتالي:

1. يقوم Codex بإضافة تفاعل 👀 على تعليقك - كإشارة تفيد بتلقي الطلب وبدء عملية الفحص.
2. يتم تشغيل المهمة السحابية لقراءة التعديلات (diff) ومقارنتها بالمعايير المحددة للمشروع (القسم 04).
3. وعند الانتهاء، يكتب المساعد ملاحظاته كتعليقات مراجعة برمجية (code review) على أسطر الكود المتأثرة مباشرة.

وتطبق المنصة إرشاداً هاماً وصارماً للمراجعات السحابية لتجنب تشتيت المطورين:

يقتصر رصد وتعليق Codex في واجهة GitHub على المشاكل ذات الأولوية P0 و P1 فقط، لحصر الملاحظات في الأخطاء الجسيمة وعالية الخطورة.

بمعنى بسيط: يتجنب المساعد كتابة تعليقات طويلة للملاحظات التجميلية أو غير الهامة. وتمثل الفئتان P0 (خطأ حرج يسبب عطل النظام) و P1 (خطأ أمني أو بنيوي هام) الأخطاء الأساسية التي يركز عليها الفحص السحابي. وتساهم هذه الفلترة في حماية صندوق الوارد من الازدحام بمئات الملاحظات البسيطة التي تغطي على الأخطاء الفعلية.

ومثال عملي: راجع المساعد تعديلاً قام به أحد زملائي الشهر الماضي لتعديل دالة معالجة الدفع، وبينما كنت أركز على مراجعة دقة الحسابات الرياضية للمبالغ، قام @codex review بكتابة ملاحظة بمستوى P1 تفيد بـ غياب معالجة تكرار الطلبات (idempotency checking) مما قد يعرض النظام لتكرار سحب المبالغ عند تكرار استدعاء الدالة. وهي ملاحظة أمنية هامة جداً سقطت مني أثناء المراجعة اليدوية.

💡 ملخص في جملة واحدة: يفعل الفحص بكتابة @codex review في تعليقات PR، ليتولى المساعد فحص التعديلات وكتابة تعليقات المراجعة؛ ويقتصر فحص المساعد على رصد الأخطاء الحرجية P0 و P1 فقط لتجنب تشتيت المطورين بالملاحظات الهامشية.

---

03 تمكين المراجعة التلقائية (Automatic Reviews)

يمثل استدعاء المراجعة يدوياً خطوة مريحة، ولكنك قد تنسى تشغيلها بانتظام - وخاصة لطلبات السحب التي يفتحها بقية أعضاء الفريق. لذا توفر المنصة خيار التمكين التلقائي للمراجعة (Automatic reviews).

تشبيه: الانتقال من الفحص الطبي الاختياري للفحص الدوري الإجباري للموظفين. يعتمد الفحص الاختياري (المراجعة اليدوية) على تذكرك للذهاب للفحص - وغالباً ما تنسى ذلك؛ بينما يفرض الفحص الدوري (المراجعة التلقائية) تشغيل الفحص لكل طلب سحب يتم فتحه تلقائياً، لحماية جودة الكود دون اعتماد على الذاكرة.

لتفعيل الخيار السحابي:

لتفعيل الفحص التلقائي لكل طلب سحب جديد، توجه لقائمة إعدادات Codex وقم بتمكين خيار Automatic reviews. لتبدأ مراجعة وتدقيق طلبات السحب تلقائياً بمجرد فتحها ودون حاجة لكتابة تعليق يدوي.

خطوات التفعيل (تتم من إعدادات حسابك في chatgpt.com وليس من موقع GitHub):

1. توجه لصفحة إعدادات مراجعة الكود في حسابك (المسار المعتمد: https://chatgpt.com/codex/settings/code-review أو ابحث عنها في خيارات حسابك تحت قسم Codex).
2. قم بتمكين خيار Automatic reviews.

بمجرد تفعيل الخيار، يتولى المساعد فحص أي PR جديد يتم فتحه تلقائياً ودون تدخل منك.

وتتوزع حالات الاستخدام بين الخيارين كالتالي:

• مستودعات الشركة والمشاريع المشتركة الهامة ← يفضل تفعيل المراجعة التلقائية لتعمل كخط فحص أمني أول يحمي الكود الأساسي من الأخطاء.
• المشاريع الشخصية والتعديلات البسيطة ← يكتفى بالاستدعاء اليدوي @codex review عند الحاجة لتجنب استهلاك الحصص السحابية دون داعٍ.
• التعديلات الكبيرة والمراجعات المتخصصة ← حتى مع تفعيل المراجعة التلقائية، يمكنك كتابة تعليق لتوجيه الفحص لزاوية معينة (مثل @codex review for security regressions كما سنوضح في القسم 04) لإعادة فحص الكود بتركيز أعلى.

وجه المقارنة	الاستدعاء اليدوي (@codex review)	المراجعة التلقائية
طريقة التشغيل	كتابة تعليق في PR عند رغبتك في الفحص	تعمل تلقائياً بمجرد فتح أي PR جديد
مخاطر النسيان	محتملة وتعتمد على تذكر المطور	غير محتملة ويعمل النظام كصمام أمان تلقائي
الاستخدام المناسب	المشاريع الشخصية والتعديلات الفرعية	مستودعات العمل المشتركة والهامة للفريق
مرونة التوجيه	تتيح كتابة شروط وتوجيهات خاصة للفحص	تغطية شاملة لجميع التعديلات تلقائياً

💡 ملخص في جملة واحدة: تفعل المراجعة التلقائية بتمكين خيار Automatic reviews في إعدادات الحساب السحابي، ليقوم Codex بمراجعة طلبات السحب تلقائياً بمجرد فتحها؛ وينصح بتفعيلها للمشاريع البرمجية الهامة والاعتماد على الاستدعاء اليدوي للمشاريع الشخصية.

---

04 تخصيص معايير الفحص بكتابة Review guidelines

قد تتساءل: ما هي المعايير والقواعد التي يستند إليها Codex لفحص الأكواد ورصد المشاكل؟ يعتمد المساعد افتراضياً على معايير جودة الكود البرمجية العامة؛ ولكن يمكنك تخصيص وكتابة شروط خاصة بمشروعك في ملف AGENTS.md.

شرحنا في المقال 11 أن ملف AGENTS.md يمثل دليل العمل والإرشادات التي يقرأها Codex قبل بدء المهام. وتمثل قواعد المراجعة قسماً مخصصاً بداخله يكتب تحت العنوان Review guidelines.

تشبيه: تزويد فاحص الجودة بقائمة فحص مخصصة لمنتجات المصنع. يملك الفاحص المعايير العامة للجودة (سلامة الهيكل، خلو المنتج من التلف)، ولكن خط الإنتاج الحالي يتطلب شروطاً خاصة للتصدير (مثل الالتزام بالمعايير البيئية ومواصفات التعبئة). وتدوين هذه الشروط في لوحة الفحص يضمن التزام الفاحص بمراجعتها وتدقيقها لكل منتج. ويمثل قسم Review guidelines في ملف AGENTS.md هذه اللوحة المخصصة للمشروع.

يكتب القسم في ملف AGENTS.md المحفوظ في جذر المشروع كالتالي:

## Review guidelines

- Don't log PII.
- Verify that authentication middleware wraps every route.

وتنص الإرشادات المكتوبة هنا على: "تجنب تسجيل بيانات المستخدمين الحساسة (PII) في السجلات"، و"التحقق من حماية كل الواجهات والمسارات باستخدام البرمجيات الوسيطة لتأكيد الهوية (authentication middleware)". وبمجرد حفظ الملف، يلتزم Codex بمراجعة وفحص التعديلات للتأكد من مطابقتها لهذه القواعد تلقائياً.

ويتبع نظام الفحص السحابي قاعدة الأولويات والأقرب للملفات الموضحة في المقال 11:

يطبق Codex إرشادات المراجعة المكتوبة في ملف AGENTS.md الأقرب للملفات المعدلة. مما يتيح لك كتابة شروط وقواعد أكثر صرامة للمجلدات الحساسة (مثل مجلد معالجة المدفوعات).

بمعنى بسيط: لا تضطر لكتابة كل القواعد في ملف الجذر العام. فإذا كان مجلد المدفوعات يتطلب شروطاً خاصة، فاحفظ ملف AGENTS.md مخصصاً في المسار src/payment/AGENTS.md؛ وعند قيام Codex بمراجعة أكواد هذا المجلد، سيقوم بقراءة وتطبيق القواعد المخصصة له تلقائياً.

مثال لإعداد ملف إرشادات مخصص في المسار src/payment/AGENTS.md:

## Review guidelines

- 校验金额必须用 Decimal，禁止用 float 做钱的运算。
- 每一笔扣款都要有幂等键，防重复回调。
- تأكد من تسجيل العمليات المالية الحساسة في السجلات المشفرة.

ليلزم المساعد بمراجعة تفاصيل معالجة المبالغ وتجنب الكسور العشرية غير الدقيقة والتحقق من شروط تكرار الطلبات تلقائياً عند فحص أكواد المدفوعات.

ويمكنك توجيه الفحص بشكل مؤقت وسريع لكتابة تركيز معين في تعليق الاستدعاء يدوياً:

@codex review for security regressions

لتطلب منه التركيز على مراجعة الثغرات الأمنية للتعديل الحالي. وإذا أردت رصد ملاحظات بسيطة (مثل الأخطاء الإملائية في الوثائق)، فيمكنك إخبار المساعد في ملف الإرشادات بـ "معاملة الأخطاء الإملائية في التوثيق كأخطاء بمستوى P1" (Treat typos in docs as P1.) ليقوم بتسجيل الملاحظة وعرضها في PR بناءً على طلبك.

💡 ملخص في جملة واحدة: تكتب قواعد المراجعة الخاصة بالمشروع تحت قسم Review guidelines في ملف AGENTS.md؛ ويطبق المساعد القواعد الأقرب للملف المعدل لتخصيص قيود المجلدات الحساسة؛ ويمكن توجيه الفحص لزاوية محددة يدوياً بكتابة @codex review for xxx.

---

05 معالجة وإصلاح الأخطاء بأمر @codex fix

عند قيام المساعد برصد مشكلة بمستوى P1 وكتابة تعليق مراجعة عليها في PR، فيمكنك الطلب منه إصلاح المشكلة وتعديل الكود مباشرة - ورفع التعديلات للفرع المخصص لطلب السحب.

تشبيه: قيام المراجع بتعديل المسودة بنفسه وإعادة إرسالها للطباعة. بدلاً من قيام المراجع بكتابة الملاحظات ومطالبتك بتعديل الكود يدوياً، يتيح لك النظام الطلب منه إجراء التعديل مباشرة وحفظه في مسودة العمل البرمجية. ولكن تشغيل هذا الإصلاح يتطلب منح المساعد الصلاحيات اللازمة للوصول للمستودع وتعديل الأكواد.

لطلب الإصلاح، اكتب تعليقاً تالياً لملاحظة المساعد بالصيغة:

@codex fix the P1 issue

وتسير عملية الإصلاح وفق الخطوات الفنية التالية الموضحة في الوثائق:

يقوم Codex بتشغيل مهمة سحابية جديدة مستعيناً بسياق طلب السحب الحالي كمرجع للعمل، ويتولى رفع التعديلات والإصلاحات لفرع PR مباشرة في حال توفرت له صلاحيات الكتابة والتعديل للمستودع.

ونوضح نقطتين هامتين تتطابقان مع قواعد الأمان والصلاحيات السابقة:

أولاً، تفعيل أمر @codex fix يطلق مهمة معالجة سحابية مستقلة. فالإصلاح لا يتم بشكل عشوائي، بل يقوم المساعد بتشغيل جلسة تفكير سحابية كاملة لقراءة الملفات وإجراء التعديل وفحصه وتأكيد سلامته قبل الرفع.

ثانياً، تتطلب العملية توفر "صلاحية الكتابة (Write access)" للمساعد. وتعتمد إمكانية رفع التعديلات للفرع بالأساس على مستوى التراخيص التي منحتها لـ Codex للمستودع. وتذكر: أن المساعد يلتزم بحدود التراخيص الممنوحة له، وتمنعه المنصة من الرفع عند الاقتصار على تراخيص القراءة فقط.

ونشير لـ قاعدة تصفية الأوامر الهامة لتجنب تداخل العمليات:

• كتابة النص @codex review (حرفياً) يوجه المساعد لـ مسار مراجعة الكود ورصد الأخطاء (للقراءة والتعليق فقط).
• وكتابة أي نص آخر بعد الإشارة @codex (مثل @codex fix the CI failures أو @codex write tests for this interface) يوجه المساعد لـ مسار المهام العامة والتعديل السحابي، فيبدأ في معالجة وكتابة الأكواد.

وتوضح الوثائق هذا الفارق:

عند كتابة طلبات غير كلمة review بعد الإشارة لـ @codex في التعليقات، يتعامل المساعد مع الطلب كمهمة برمجة عامة ويستعين بسياق PR للبدء في كتابة وتعديل الملفات.

وتذكر دائماً القاعدة الأمنية والعملية الهامة: تتيح لك ميزة @codex fix اختصار الوقت وإصلاح الأخطاء وتحديث الفرع، ولكن قرار دمج الفرع بالفرع الرئيسي (Merge) يتطلب موافقتك اليدوية الصريحة ونقرك على زر الدمج - لتظل مسؤولية اعتماد الأكواد وتأمينها في يدك.

💡 ملخص في جملة واحدة: يتيح أمر @codex fix the P1 issue تفعيل مهمة سحابية لتعديل الكود ورفعه لفرع PR مباشرة بشرط توفر صلاحيات الكتابة؛ وتذكر أن كلمة review مخصصة للفحص، وتوجه الكلمات الأخرى المساعد للكتابة والتعديل؛ ويقتصر قرار الدمج النهائي على موافقتك يدوياً.

يوضح المخطط التالي دورة معالجة وتدقيق طلب السحب (PR) بالكامل:

يوضح المخطط مسار العمل: يبدأ الفحص تلقائياً بمجرد فتح PR أو يدوياً بكتابة تعليق @codex review؛ ليقوم المساعد بقراءة التعديلات في السحابة ومطابقتها مع إرشادات AGENTS.md المحلية وكتابة تعليقات مراجعة بمستوى P0/P1 على الملفات؛ ويسهل طلب الإصلاح بكتابة @codex fix لتحديث الفرع وإعادة تشغيل الفحص للتأكد من سلامة الكود.

---

06 الفحص المحلي عبر الطرفية (أمر /review)

شرحنا خطوات المراجعة السحابية على موقع GitHub. ونعرض هنا أسلوباً برمجياً هاماً وعملياً يسبق رفع الأكواد: إجراء الفحص الذاتي محلياً على جهازك قبل فتح طلب السحب وتوثيق التعديلات.

تشبيه: مراجعة ورقة الامتحان وتعديل الأخطاء بقلم الرصاص قبل تسليمها للجنة. بدلاً من رفع أكواد تحتوي على أخطاء واضحة ليقوم المساعد أو الفريق بكتابة ملاحظات عليها في GitHub، يفضل إجراء فحص ذاتي محلي وتصحيح المشاكل مسبقاً. مما يوفر الوقت ويظهر كودك بشكل احترافي.

اكتب الأمر المائل التالي داخل محادثة Codex في الطرفية:

/review

ستظهر قائمة بالخيارات والتهاميات المتاحة للفحص محلياً، ويقوم المساعد بقراءة التعديلات وعرض الملاحظات المنسقة بحسب الأولوية ودون تعديل أي ملف في مشروعك (للقراءة فقط). وتضم القائمة الخيارات التالية:

• Review against a base branch (المقارنة بفرع رئيسي): تحديد فرع برمجى للمقارنة، ليقوم Codex بالبحث عن نقطة التفرع المشتركة وقراءة التعديلات الحالية وعرض المشاكل قبل إرسال وتصدير الكود لفرع PR.
• Review uncommitted changes (فحص التعديلات غير المرفوعة): فحص كل الملفات المعدلة الحالية (سواء كانت مضافة للمرحلة stage، غير مضافة، أو ملفات جديدة غير متتبعة) لتنقية الكود وتأمين العمل قبل الرفع.
• Review a commit (فحص commit محدد): اختيار تعديل محدد من سجل التعديلات المكتملة وطلب مراجعته بالكامل.
• Custom review instructions (إرشادات فحص مخصصة): كتابة طلب توجيهي مخصص للفحص (مثل "ركز على مراجعة شروط الوصول وسهولة استخدام واجهة المستخدم") ليلتزم المساعد بها.

ونوضح إعداداً تقنياً مفيداً: يعتمد فحص /review افتراضياً على النموذج المعتمد للمحادثة؛ ولتخصيص نموذج قوي ودقيق لمعالجة الملاحظات، يمكنك ضبط حقل النموذج المخصص للمراجعات review_model في ملف config.toml يدوياً لتسريع الفحص ودقته.

ويتلخص مسار العمل المقترح للمراجعات في الخطوات الثلاث التالية:

1. عند انتهاء كتابة الأكواد، اكتب أمر /review واختر خيار Review uncommitted changes لفحص التعديلات الحالية على جهازك.
2. راجع الملاحظات والتحذيرات المعروضة وقم بإصلاح وتعديل الملفات يدوياً لحل المشاكل.
3. بعد تنظيف الكود، قم بكتابة commit ورفع التعديلات وفتح PR - لتضمن خلو الأكواد من الأخطاء الواضحة وتسهل مراجعتها سحابياً.

ويساهم هذا الفحص المسبق في تقليص الملاحظات والتعليقات المكتوبة على PR لاحقاً للنصف وتسهيل اعتماد الأكواد.

💡 ملخص في جملة واحدة: يمثل أمر /review المحلي أداة للفحص الذاتي قبل رفع الكود؛ ويعمل للقراءة فقط لفحص التعديلات الحالية أو المقارنة بالفروع أو المراجعة المخصصة؛ وينصح بإصلاح الأخطاء محلياً أولاً لتبسيط المراجعات السحابية؛ ويمكن تخصيص نموذج قوي للمراجعة عبر مفتاح review_model.

---

07 تهيئة وتوثيق ترخيص أداة GitHub CLI (أداة gh)

عند استخدام تطبيق سطح المكتب لـ Codex أو إضافات محررات الأكواد IDE، يوصى بشدة بتثبيت وتوثيق أداة GitHub CLI الرسمية (gh) لتسهيل الاتصال.

تشبيه: تزويد مساعدك ببطاقة تصريح دخول الأرشيف للمشروع. بدون التصريح، يعرف المساعد بوجود طلب سحب ولكن يمنع من قراءة تعليقات المطورين ومراجعة مسارات الملفات والاطلاع على التعديلات السابقة؛ ومنحه التصريح (توثيق ترخيص gh) يتيح له جلب كل تفاصيل وسجلات PR وعرضها في واجهة العمل.

تنص الإرشادات على أهمية توثيق الأداة كالتالي:

يتطلب تمكين Codex من قراءة تفاصيل PR ومراجعة تعليقات المطورين والملفات المعدلة تثبيت أداة GitHub CLI وتوثيق تراخيصها عبر أمر gh auth login. وغياب الأداة أو التوثيق يمنع عرض تفاصيل طلبات السحب في لوحة المراجعات الجانبية للتطبيق.

ويتم تثبيت الأداة وتوثيق الترخيص بحسب نظام التشغيل كالتالي:

# لأنظمة macOS (باستخدام Homebrew)
brew install gh

# لأنظمة Windows (باستخدام winget)
winget install --id GitHub.cli

# لتوثيق وتفعيل ترخيص الحساب (لكل الأنظمة بعد التثبيت)
gh auth login

ℹ️ لأنظمة Linux، تختلف أوامر التثبيت بحسب التوزيعة المستخدمة (استخدم مدير الحزم المتوافق مثل apt أو dnf)، وتتبع نفس خطوات التوثيق بأمر gh auth login بعد التثبيت.

وبعد اكتمال التوثيق، تسير دورة إصلاح وتعديل الأخطاء داخل التطبيق كالتالي:

1. فتح لوحة المراجعات لفرع PR المستهدف.
2. قراءة تفاصيل PR وتعليقات المطورين والملفات المتأثرة.
3. توجيه Codex لإصلاح النقاط المكتوبة في تعليقات محددة.
4. مراجعة التغييرات المقترحة وفحص سلامتها (diff).
5. وبعد التأكد والموافقة، قم بإضافة التعديلات للمرحلة stage وكتابة commit ورفعها للفرع.

لاحظ أن خطوة الرفع وتحديث الفرع تظل معلقة بانتظار موافقتك الصريحة لحماية الأكواد.

وتذكر التنبيه الأمني الهام المتعلق بـ هجمات حقن التعليمات: تمثل تعليقات طلبات السحب وملاحظات المطورين نصوصاً خارجية جلبها المساعد من الإنترنت، وقد تحتوي على تعليمات خبيثة موجهة لخداع الذكاء الاصطناعي. لذا راجع التعليمات والطلبات وتجنب السماح للمساعد بـ "تنفيذ الأوامر البرمجية المكتوبة في التعليقات تلقائياً ودون فحص يدوي مسبق".

💡 ملخص في جملة واحدة: يساعد تثبيت أداة gh وتوثيق ترخيصها عبر gh auth login Codex في قراءة تفاصيل PR وتعليقات المطورين والملفات وعرضها في التطبيق؛ وتظل خطوة الرفع معلقة بموافقتك اليدوية؛ واحذر من الأوامر المكتوبة في تعليقات الويب.

---

08 الحدود الأمنية الصارمة: حظر دمج الفروع أو الرفع الإجباري تلقائياً

شرحنا الميزات المسهلة للعمل. ونؤكد هنا على الحدود الأمنية الصارمة التي يجب الالتزام بها يدوياً لحماية كود المشروع البرمجي وسجلات التعديل من التلف.

تشبيه: قيام مساعدك بصياغة وتدقيق العقود القانونية، وحصر التوقيع والختم الرسمي على المدير التنفيذي فقط. يتولى المساعد صياغة البنود وتعديل الملاحظات بدقة وتجهيز العقد؛ ولكن توقيع العقد يترتب عليه التزامات مالية وقانونية لا يمكن التراجع عنها، لذا يشترط التوقيع اليدوي للمسؤول التنفيذي حصراً. ويمثل دمج طلب السحب بالفرع الرئيسي (Merge) أو الرفع الإجباري لتعديل السجلات (force-push) خطوة التوقيع والختم الرسمي لـ Git.

يوضح الجدول التالي تصنيف الصلاحيات والمسؤوليات البرمجية:

العملية	هل يمكن إسنادها للمساعد؟	المسؤول عن التنفيذ
فحص الأخطاء وعرض الملاحظات (@codex review أو /review)	✅ نعم، مسموح وآمن	المساعد (للقراءة والكتابة التعليقية فقط)
إصلاح الأخطاء ورفعها لفرع PR المخصص (@codex fix)	✅ نعم، بعد مراجعتك للتعديل	المساعد (يحتاج صلاحيات الكتابة للفرع)
دمج طلب السحب بالفرع الرئيسي (Merge)	⚠️ يحظر إسنادها وتعتبر خطوة غير قابلة للتراجع	المطور يدوياً وبنفسه
الرفع الإجباري وتعديل السجلات (git push --force)	❌ خط أحمر أمني ويحظر تشغيلها نهائياً	المطور يدوياً وبحذر شديد

ونلتزم بالقاعدتين الأمنيتين التاليتين:

أولاً، إتمام دمج طلب السحب بالفرع الرئيسي (Merge) يدوياً وبموافقتك. يستطيع Codex مراجعة الأخطاء وإصلاحها وتحديث فرع PR - وهي عمليات تقع داخل فرع مؤقت يمكن حذفه وتعديله بأمان عند الخطأ. ولكن دمج الفرع بالفرع الرئيسي main يعني دخول الأكواد لخط الإنتاج الفعلي للفريق، وتأثيرها على بقية المطورين، لذا يشترط مراجعتها يدويًا والنقر على زر القبول والدمج بنفسك للتأكد من ملاءمة الوقت والتغييرات.

ثانياً، منع استخدام أوامر الرفع الإجباري git push --force نهائياً من قبل المساعد. يترتب على تشغيل الرفع الإجباري تعديل سجلات وتاريخ Git وكتابة تعديلات فوق أكواد بقية المطورين مما قد يسبب فقد البيانات وصعوبة استعادتها. ويجب حصر استخدام هذا الأمر للمطور البشري يدوياً مع التحقق الدقيق من اسم الفرع المستهدف قبل الإرسال. ولتفادي المشاكل، احرص على منع المساعد من استخدام الأمر.

وتتوافق هذه القيود مع الفلسفة الأمنية لـ Codex المشروحة في المقال 15: حيث يقتصر وضع الصلاحيات التلقائي لأمر codex exec على القراءة فقط read-only، ويتطلب تشغيل التعديل موافقتك الصريحة وكتابة خيار --sandbox workspace-write يدوياً. فكلما زادت خطورة العملية وتأثيرها البرمجي، وجب حصر اتخاذ القرار في يد المطور البشري.

💡 ملخص في جملة واحدة: يقتصر دور Codex على المراجعة والإصلاح ورفع التعديلات للفرع الفرعي؛ ويحظر إسناد مهام الدمج بالفرع الرئيسي (Merge) أو الرفع الإجباري (force-push) للمساعد، وتظل مسؤولية اتخاذ هذه القرارات غير القابلة للتراجع في يد المطور يدوياً.

---

09 مسار مراجعة واعتماد الكود البرمجي بالتكامل مع المساعد

نلخص دورة فحص وتأمين طلبات السحب بالاستعانة بالخطوات السحابية والمحلية الموضحة في المخطط التالي:

يوضح المخطط خطوات تنظيم العمل: بدء المراجعة بالفحص الذاتي المحلي /review وتعديل الأخطاء مسبقاً (باللون الأخضر الآمن للقراءة) ← رفع التعديلات وفتح PR لتفعل المراجعة التلقائية أو اليدوية @codex review وكتابة الملاحظات بمستوى P0/P1 في GitHub ← الطلب منه إصلاح المشاكل بأمر @codex fix وتحديث الفرع بالتكرار ← وحصر خطوة الدمج النهائي (Merge) باللون الأحمر في يد المطور البشري لتأمين المشروع.

يساعدك هذا النموذج في توظيف الذكاء الاصطناعي لتسريع عمليات التدقيق وفحص الأخطاء، مع الحفاظ على أمان واستقرار الأكواد في الفرع الرئيسي للمشروع.

---

10 تدريب عملي: تشغيل فحص الكود محلياً باستخدام /review

نظراً لاعتماد المراجعات السحابية على الروابط والاشتراكات السحابية، نطبق معاً تدريباً عملياً متكاملاً لتشغيل الفحص الذاتي محلياً على جهازك باستخدام أمر /review لرصد الأخطاء البرمجية (مثل ثغرات حقن SQL) والتأكد من بقاء الملفات سليمة.

الخطوة الأولى: تهيئة مستودع Git وكتابة كود يحتوي على ثغرة أمنية (تكتب في الطرفية العادية)

mkdir review-demo && cd review-demo
git init
printf 'def get_user(uid):\n    return db.query("SELECT * FROM users WHERE id=" + uid)\n' > app.py
git add app.py && git commit -m "feat: 初始 get_user"

المتوقع: إنشاء المجلد وتهيئته كمستودع Git وكتابة الكود والالتزام بأول عملية commit بنجاح مع ظهور رسائل التوثيق المعتادة في الطرفية. لاحظ كتابة دالة استعلام برمجية تعتمد على دمج النص مباشرة مع المعامل uid - مما يمثل ثغرة أمنية خطيرة لحقن SQL (SQL Injection) وسنرى كيف يتعامل المساعد معها.

الخطوة الثانية: كتابة كود إضافي وتعديل الملف دون رفع التعديلات

printf 'def get_user(uid):\n    return db.query("SELECT * FROM users WHERE id=" + uid)\n\ndef delete_user(uid):\n    db.execute("DELETE FROM users WHERE id=" + uid)\n' > app.py

المتوقع: كتابة دالة الحذف الجديدة وتعديل الملف بنجاح. ويمثل التعديل حالياً كوداً معدلاً في مجلد العمل ولم يضف للمرحلة stage أو يرفع بعد، لتجربة خيار فحص التعديلات غير المرفوعة.

الخطوة الثالثة: تشغيل Codex وبدء فحص المراجعة

codex

اكتب الأمر المائل لبدء المراجعة:

/review

المتوقع: ظهور قائمة خيارات المراجعة، استخدم الأسهم لاختيار خيار Review uncommitted changes (فحص التعديلات غير المرفوعة) واضغط زر الإدخال.

الخطوة الرابعة: مراجعة ملاحظات وتوجيهات المساعد

المتوقع: سيقوم Codex بتشغيل معالج المراجعة وقراءة التعديلات في الملف وعرض الملاحظات في الطرفية. وسيقوم برصد ثغرة حقن SQL في دالة الحذف delete_user (لاعتمادها على دمج النصوص البرمجية مباشرة مع المعاملات)، ويعرض تنبيهاً بمستوى خطورة عالٍ ويوجهك لاستخدام الاستعلامات المعلمة (parameterized queries) لحل المشكلة. وتلاحظ بقاء ملف app.py دون أي تعديل لكون الخطاف للقراءة فقط.

وهذا يثبت نجاح التعرف على الأخطاء الأمنية الجسيمة تلقائياً ومحلياً قبل التصدير.

الخطوة الخامسة: تنظيف مجلد التدريب (اختياري)

cd .. && rm -rf review-demo

بإتمام هذه الخطوات، تكون قد تحققت عملياً من مسار المراجعة الذاتية للأكواد محلياً وبشكل آمن تماماً.

💡 ملخص في جملة واحدة: خطوات التدريب هي: إنشاء مستودع Git وكتابة كود يحتوي على ثغرة أمنية ← تعديل الملف وإبقاء التغييرات غير مرفوعة ← تشغيل المساعد وأمر /review لمراجعة التغييرات غير المرفوعة ← التأكد من رصد الثغرة وبقاء الملف دون تعديل؛ لإتقان الفحص الذاتي للكود.

---

11 ملخص

شرحنا في هذا المقال تكامل Codex مع Git و GitHub - وكيفية تفعيل مراجعة الكود سحابياً ومحلياً، وتخصيص شروط الفحص، وإصلاح الأخطاء، والالتزام بحدود الصلاحيات الأمنية.

دعنا نلخص النقاط الأساسية معاً بشكل سريع:

الجانب	المفهوم الأساسي	نقاط هامة
طريقتان للمراجعة	سحابي عبر GitHub ومحلي عبر الطرفية	@codex review في السحابة لتسجيل الملاحظات في PR؛ وأمر /review محلياً للفحص الذاتي للقراءة فقط
مراجعة GitHub	الاستدعاء اليدوي أو المراجعة التلقائية	@codex review يدوياً أو تفعيل Automatic reviews سحابياً لتشغيل الفحص لكل PR تلقائياً؛ ويركز على مستويات P0/P1
قواعد الفحص	كتابة الشروط في ملف AGENTS.md	يكتب تحت قسم Review guidelines؛ ويطبق المساعد الإرشادات الأقرب للملف المعدل لمرونة القيود
إصلاح الأخطاء	أمر الإصلاح السحابي @codex fix	يوجه المساعد لتعديل الكود ورفع الإصلاح لفرع PR مباشرة بشرط توفر صلاحيات الكتابة للمستودع
أداة GitHub CLI	تثبيت وتوثيق أداة gh	يتيح لـ Codex جلب تفاصيل PR وتعليقات المطورين وعرضها في التطبيق، وتفعيل التوثيق بأمر gh auth login
الحدود الأمنية	حظر دمج الفروع أو الرفع الإجباري تلقائياً	تظل قرارات دمج طلب السحب (Merge) أو الرفع الإجباري (force-push) قرارات بشرية يدوياً لحماية الأكواد

يجب أن تكون الآن قادراً على: التمييز بين المراجعة السحابية والفحص الذاتي المحلي واختيار المسار المناسب؛ واستدعاء المراجعة يدوياً وتفعيل المراجعة التلقائية لطلبات السحب؛ وتخصيص قواعد الفحص لملفات المشروع ومجلداته الحساسة؛ واستخدام أوامر الإصلاح التلقائي وتأمين الصلاحيات؛ وربط أداة GitHub CLI بالبرنامج؛ والالتزام بحدود الصلاحيات البشرية وتجنب الأخطاء غير القابلة للتراجع. هذه القدرة على مراجعة الكود وإصلاح الأخطاء بالتكامل مع Git تضمن حماية مستودعات كود فريقك من الثغرات البرمجية والسرعة في اعتماد التعديلات البرمجية.

تذكر دائماً القواعد الأمنية - واحفظ قواعد "الفحص الذاتي محلياً قبل الرفع، وتوجيه المراجعات السحابية للأخطاء الحرجية، وحظر دمج الفروع أو الرفع الإجباري تلقائياً، والتحقق اليدوي الصارم قبل الدمج" لتأمين وتسريع العمل.

---

المقال التالي [27 · التشغيل الآلي والتكامل المستمر (CI/CD)] - ساعدنا تكامل Git و GitHub على مراجعة طلبات السحب وإصلاح الأخطاء بنجاح بالتفاعل مع تعليقات المطورين. ولكن كيف نقوم بنقل هذه الخطوات البرمجية لتعمل بشكل مؤتمت بالكامل وبشكل مستقل دون انتظار تعليقات بشرية؟ سنتحدث في المقال القادم بالتفصيل عن التشغيل الآلي والـ CI/CD: وكيفية إدراج أوامر Codex في خطوات البناء البرمجي المؤتمتة (مثل GitHub Actions) لإصلاح أعطال البناء وتحديث الأكواد وفتح PRs تلقائياً في الخلفية، للوصول لمرحلة العمل المؤتمت المستقل بالكامل.

---

قراءات مقترحة

• دليل مهارات الوكيل (Skills): حزم خطوات وسير العمل المكرر وتسهيل استدعائه
• مشروع عمل متكامل: بناء أداة وإصلاح أخطائها ورفعها خطوة بخطوة
• إضافات محررات الأكواد (VS Code وغيرها)