أربعة سير عمل يومية: الاستكشاف، إصلاح الأخطاء، إعادة الهيكلة، كتابة الاختبارات
📚 التنقل في السلسلة: الجزء السابق 13 · كتابة التعليمات (Prompt) علّمك "كيف تقول الكلام" — كيف تحوّل المتطلب الضبابي إلى تعليمات دقيقة يفهمها Codex. هذا الجزء يُنزل ذلك إلى الواقع: 80% من عملك اليومي لا يخرج عن أربعة أنواع، وكل نوع يحمل سير عمل يمكن نسخها ولصقها مباشرةً. الجزء التالي 15 · الصلاحيات، الحاوية الرملية والموافقات.
استمع إلى هذه المحادثة. الأسبوع الماضي سألني أحدهم في المجموعة وكان قد انتقل لاستخدام Codex للتو:
"أعطيته إصلاح خطأ، فمحا رسالة الخطأ بسرعة، وأرسلت الكود. في اليوم التالي ظهرت نفس المشكلة مجددًا، ما السبب؟"
سألته: "هل طلبت منه أولًا تحديد السبب الجذري؟ هل أضفت اختبار انحدار (regression test)؟"
قال: "... آه؟ أليس إصلاح الخطأ هو محو رسالة الخطأ؟"
المشكلة هنا واضحة. اعتبر "اختفاء رسالة الخطأ" = "حلّ المشكلة"، ولم يُثبّت القفل على ذلك الخطأ. في الواقع، لكل من هذه الأنواع الأربعة — الاستكشاف، إصلاح الأخطاء، إعادة الهيكلة، كتابة الاختبارات — أسلوبه الثابت. الأسلوب الصحيح يجعل Codex سريعًا وموثوقًا؛ الأسلوب الخاطئ يُنجز الظاهر ويدفن الألغام.
الجزء السابق تناول "تقنيات الكلام" العامة. هذا الجزء يُهبطها إلى أربعة سيناريوهات متكررة. استخلصتُ هذه الأساليب الأربعة بعد نصف عام من استخدام Codex، وكلها تسير مع طبيعة Codex — في IDE يرى ملفاتك المفتوحة، في CLI عليك استخدام @ لتحديد الملفات؛ يُتقن الأعمال التي يستطيع التحقق منها بنفسه، لذا اترك له نافذةً للتحقق.
بعد قراءة هذا الجزء ستحصل على:
- سير عمل قابلة للنسخ لكل من الأنواع الأربعة الشائعة (استكشاف / إصلاح خطأ / إعادة هيكلة / كتابة اختبارات)، مع الفرق بين IDE وCLI
- السبب وراء كل خطوة، لا مجرد حفظ قوالب
- جدول ملخص لأساليب المهام الأربع
- تطبيق عملي كامل مع نتائج متوقعة (إصلاح خطأ حقيقي من البداية للنهاية)
⚠️ كل ما يتعلق بأوامر محددة وأوامر الشرطة المائلة والسلوكيات الافتراضية مستند إلى الوثائق الرسمية لـ Codex؛ أسماء النماذج وواجهات المستخدم عرضة للتغيير بحسب الإصدار.
01 تعرّف أولًا: أربعة أنواع، أربع أدوات
قبل البدء، وضّح "طبيعة" كل من الأنواع الأربعة. متطلباتها من Codex مختلفة تمامًا، الأداة الخاطئة تُعطي نتائج أقل بكثير.
مثال توضيحي: أربع سكاكين في المطبخ لكل منها استخدامه. سكين الفيليه لتقطيع السمك، وسكين الساطور للعظم. لو أخذت سكين الفيليه للعظم سيتكسر حتمًا. الاستكشاف، إصلاح الأخطاء، إعادة الهيكلة، كتابة الاختبارات — أربع سكاكين مختلفة. المهم ليس "هل تعرف استخدام Codex" بل "أي سكين هذه المهمة تحتاج".
أهم فارق بينها: هل تُعدّل الكود؟
| النوع | يُعدّل الكود؟ | ما يفعله Codex أساسًا | ما عليك مراقبته |
|---|---|---|---|
| استكشاف المستودع | لا (قراءة فقط) | يقرأ الملفات ويشرح | صحة الشرح |
| إصلاح خطأ | نعم | إعادة الإنتاج + تحديد السبب الجذري + الإصلاح | السبب الجذري صحيح؟ اختبار الانحدار موجود؟ |
| إعادة الهيكلة | نعم (السلوك لا يتغير) | إعادة كتابة مكافئة | هل تغيّر السلوك بعد الإصلاح؟ |
| كتابة الاختبارات | يضيف ملفات | ينتج اختبارات + يُغطي الحالات الحدية | هل الحالات الحدية مُغطاة بالكامل؟ |
لاحظ؟ الاستكشاف خطره صفر (يقرأ فقط لا يكتب)، لذا اسأل بحرية؛ إصلاح الأخطاء وإعادة الهيكلة يُعدّلان، اطلب منه أن يشرح أولًا ثم يُعدّل؛ كتابة الاختبارات بينهما، ينشئ ملفات جديدة لا يمسّ كودك الحالي، لكن راقب ألا يُرضي نفسه باختبار "الحالة العادية" فقط.
خلاصة من الوثائق الرسمية تستحق أن تُعلَّق على الجدار:
Codex ينتج جودة أعلى بكثير حين يستطيع التحقق من عمله. أعطه خطوات إعادة الإنتاج، وطريقة التحقق، وأوامر lint واختبارات ما قبل الإيداع — فيكون لديه ما يستند إليه بدلًا من "يبدو صحيحًا".
هذه الجملة هي الأساس للأساليب الأربعة الآتية. كل قسم يُجيب في جوهره على: كيف أترك لـ Codex نافذةً ليتحقق من نفسه في هذا النوع؟
💡 خلاصة بجملة واحدة: ميّز "طبيعة" الأنواع الأربعة أولًا بـ"هل تُعدّل الكود؟" — الاستكشاف خطره صفر اسأل بحرية، ما يُعدّل اطلب الشرح أولًا ثم التعديل؛ ولكل نوع اترك لـ Codex نافذةً للتحقق من نفسه.
02 استكشاف مستودع غريب: ثلاث طبقات من الكبير للصغير
أكثر السيناريوهات تكرارًا: تتسلم مشروعًا غريبًا وتريد فهمه أولًا.
كيف كنت تفعل ذلك قبلًا؟ تفتح المجلد، تحدق في عشرات الأدلة، تضغط ملفًا تلو الآخر، وبعد ساعتين لا تزال في ضباب. الآن لا حاجة — Codex يعامل مشروعك كمساحة عمله، يقرأ الكود وحده، وعليك فقط السؤال.
مثال توضيحي: الدخول لمجمع تجاري لأول مرة — أنظر لوحة التوجيه أولًا، ثم أبحث عن المتجر، ثم أتبع المسار. لن تدخل مباشرةً لرف معين وتبحث، بل ستقف في الصالة وتنظر أولًا "كم طابقًا وماذا في كل طابق" (البنية العامة)، ثم "الأم والطفل في أي طابق وأي منطقة" (تحديد الوحدة)، ثم "كيف أسلك من المدخل لذلك المتجر" (تتبع المسار). من الكبير للصغير، من الكل للتفاصيل — هذا هو إيقاع الاستكشاف.
نقطة مهمة تتعلق بكيفية استخدام كل من IDE وCLI — امتداد IDE وCLI لـ Codex يختلفان في طريقة الحصول على السياق: امتداد IDE يُضيف تلقائيًا السياق من الملفات المفتوحة والنص المحدد، لكن Codex CLI لا يفعل ذلك — عليك استخدام @ لتحديد الملفات صراحةً حتى يتمكن من "رؤيتها".
في IDE (الاستكشاف المحلي الأسرع)
افتح الملفات الأكثر صلةً، وحدّد الأسطر التي تُثير اهتمامك (اختياري لكن موصى به)، ثم اسأل. مثال من الوثائق الرسمية:
اشرح كيف يتدفق الطلب عبر الكود الذي حددته.
تضمّن:
- ما يتحمله كل وحدة مشاركة، باختصار
- أي البيانات يُتحقق منها وأين
- تحذيرَين أو ثلاثة من "المزالق" عند تعديل هذا الجزءلمراجعة سريعة أضف:
لخّص مسار الطلب في قائمة مرقمة، ثم اذكر الملفات المعنية.في CLI (للسجلات النصية القابلة للتمرير + أوامر الطرفية)
شغّل الجلسة التفاعلية:
codexثم استخدم @ لتحديد الملفات (هذا الفارق الأساسي بين CLI وIDE — عليك أنت تحديد الملفات):
أريد فهم البروتوكول الذي تستخدمه هذه الخدمة. اقرأ @foo.ts @schema.ts،
وشرح بنية البيانات ومسار "الطلب/الاستجابة"، مع التركيز على الحقول الإلزامية
والاختيارية، وقواعد التوافق مع الإصدارات السابقة.عادة مستقرة أستخدمها دائمًا عند تسلم مشروع جديد: أثناء الاستكشاف، اضبط الصلاحيات على "للقراءة فقط". شرحنا /permissions في 12 · أوامر الشرطة المائلة، وأثناء الاستكشاف أحوّلها لـ Read Only — اجعله يقرأ ويشرح فقط، لا يُعدّل ملفًا أبدًا. الاستكشاف يجب أن يكون خطره صفرًا، أغلق هذا القفل أولًا.
| الخطوة | امتداد IDE | CLI |
|---|---|---|
| 1. أعطِ السياق | افتح الملفات ذات الصلة، حدد الأسطر | استخدم @اسم_الملف أو /mention |
| 2. اسأل عن البنية العامة | "نظرة عامة على البنية، مسؤولية كل وحدة" | نفسه، الملفات محددة بـ @ |
| 3. حدد الوحدة | "الكود المسؤول عن [وظيفة معينة] في أي ملفات" | نفسه |
| 4. تتبع المسار | "تتبع المسار الكامل لـ [مسار معين]" | نفسه |
| 5. اطلب ناتجًا قابلًا للتحقق | "لخّص في قائمة مرقمة + قائمة الملفات المعنية" | نفسه |
| طوال الوقت | لا تدعه يُعدّل الكود | حوّل لـ Read Only |
💡 خلاصة بجملة واحدة: إيقاع الاستكشاف — ثلاث طبقات من الكبير للصغير: البنية العامة، تحديد الوحدة، تتبع المسار؛ تذكّر الفارق: IDE يرى الملفات المفتوحة تلقائيًا، CLI يحتاج
@منك، واجعله "للقراءة فقط" طوال الوقت.
03 إصلاح خطأ: إعادة إنتاج → تحديد السبب → إصلاح → تشغيل التحقق
إصلاح الأخطاء من أكثر الأنواع تكرارًا، وأكثرها عرضةً للانحراف — هذا ما وقع فيه صاحبنا في مقدمة الجزء.
لماذا ينحرف؟ لأن أكثر الأخطاء الشائعة: إلقاء رسالة الخطأ وقول "أصلحها"، فينتج Codex إصلاحًا "يُخفي رسالة الخطأ". انتبه، "اختفاء رسالة الخطأ" ≠ "حل المشكلة" — كثيرًا ما يُغطي الأعراض فحسب، والسبب الجذري لا يزال مختبئًا يتربص.
مثال توضيحي: مواسير مياه تتسرب، لا تكتفِ بوضع دلو. الماء على الأرض يُعطي إشارةً، لكن الدلو أو القماش فقط (إخفاء رسالة الخطأ) ليس علاجًا — عليك أولًا تتبع أثر الرطوبة للعثور على الأنبوب المتشقق (تحديد السبب الجذري)، استبداله، ثم فتح المياه والتأكد من عدم التسرب (التحقق). إصلاح الأخطاء تمامًا مثل ذلك — ابحث عن نقطة التسرب، لا تضع دلوًا.
الأسلوب الرسمي لـ Codex في إصلاح الأخطاء يرتكز على إعطائه "وصفة إعادة الإنتاج" لا وصفًا عامًا. تقول الوثائق الرسمية:
ما تُقدّمه أنت: خطوات إعادة الإنتاج والقيود — هذه أكثر قيمةً بكثير من وصف عام. ما يُقدّمه Codex: خرج الأوامر، نقاط الاستدعاء التي يجدها، سجل المكدس الذي يستثيره.
الأسلوب الصحيح لإصلاح الخطأ أربع خطوات لا تُقطع:
- أعطِ وصفة إعادة الإنتاج + الملفات المشتبه بها: رسالة الخطأ كاملةً + "ضغطت هنا وفعلت كذا ثم ظهر الخطأ"، وأضف الملفات التي تشك فيها
- اطلب إعادة الإنتاج أولًا ثم السبب الجذري: الوثائق الرسمية تنصح بالنص الصريح "أعد إنتاج الخطأ محليًا أولًا" — حين يُعيد إنتاجه، يكون حكمه على السبب الجذري أكثر موثوقية
- الإصلاح: بعد تأكيد السبب الجذري، اطلب الإصلاح مع التنبيه "حافظ على أصغر تغيير ممكن"
- تشغيل التحقق: يجب على Codex إعادة تشغيل خطوات إعادة الإنتاج بعد الإصلاح؛ إذا كان لديك سير تحقق قياسية اطلب "تشغيل lint + أصغر مجموعة اختبارات ذات صلة وأخبرني بالأوامر والنتائج"
الخطوة الرابعة أكثر ما يُغفله المبتدئون، لكنها الأثمن. الوثائق الرسمية في "التحقق بعد الإصلاح" تُقدّم جملةً واحدة:
بعد الإصلاح، شغّل lint + أصغر مجموعة اختبارات ذات صلة. أخبرني بالأوامر المستخدمة والنتائج.هذا يُقفل الخطأ — الاختبارات تتحول للون الأخضر بعد الإصلاح، وأي شخص يُعيد فتح نفس الأمر مستقبلًا سترتد الاختبارات للأحمر فورًا. لم يُثبّت صاحبنا هذا القفل، لذا عاد الخطأ.
هيكل سريع لإصلاح الأخطاء (انسخه):
الخطأ: [وصف الظاهرة بجملة]
إعادة الإنتاج: [رقّم كل خطوة من التشغيل للتشغيل]
القيود: [ما لا يُمسّ، حجم التغيير]
الملفات المشتبه بها: [إن تمكنت من تحديدها، استخدم @]
المطلوب: إعادة إنتاج أولًا → تحديد السبب الجذري (لا تُعدّل بعد) → أصغر إصلاح → تشغيل lint والاختبارات ذات الصلة وإبلاغي.💡 خلاصة بجملة واحدة: إصلاح الخطأ أربع خطوات — أعطِ وصفة إعادة إنتاج، اطلب الإنتاج أولًا ثم السبب الجذري، أصغر إصلاح، تشغيل lint والاختبارات للتحقق؛ وصفة الإعادة أكثر قيمةً من وصف عام، والتحقق هو القفل الذي يمنع عودة نفس الخطأ.
04 إعادة الهيكلة: خطة أولًا → تغييرات صغيرة → السلوك لا يتغير → اختبار قبل وبعد
إعادة الهيكلة الأعلى خطرًا لأنها تُعدّل كودًا "لا عيب فيه".
إصلاح الأخطاء له معيار واضح للاكتمال — اختفاء الخطأ وتحول الاختبارات للأخضر. إعادة الهيكلة ليس لها معيار بتلك الوضوح، هدفها "الكود أنظف، لكن السلوك الخارجي لا يتغير بأي حرف". حين يتغيّر السلوك، تكون قد أدخلت خطأً باسم إعادة الهيكلة، وهذا أخطر أنواع الأخطاء لأنه لا أحد يتوقع اختبار "شيء رُتِّب فقط".
مثال توضيحي: استبدال قطعة في قطار يسير، دون إيقافه أو إزعاج الركاب. عليك ضمان استمرار السير وعدم شعور الركاب بأي تغيير، لكن القطعة تحت تُستبدل بأفضل. إعادة الهيكلة هي "استبدال القطع أثناء السير" — الخدمة الخارجية (تجربة الراكب) يجب أن تبقى متطابقة.
أكثر أسباب فشل إعادة الهيكلة: إعادة كتابة دفعةً واحدة (تغيير كبير لا يمكن التحقق منه تدريجيًا)، وغياب الاختبارات كضمانة (السلوك تغيّر أو لم يتغيّر بحسب التخمين فقط). الأسلوب الرسمي لـ Codex يعالج هذا مباشرةً — الخطة أولًا، ثم التنفيذ خطوةً خطوة.
الخطوة الأولى: اطلب خطة إعادة الهيكلة أولًا
تنصح الوثائق الرسمية بطلب خطة قبل التعديل. إذا كان لديك مهارة (skill) $plan، استدعها صراحةً (المهارات تُستدعى بـ $، وهي مختلفة عن /plan). مثال من الوثائق الرسمية:
$plan
نريد إعادة هيكلة نظام auth الفرعي، الهدف:
- فصل المسؤوليات (تحليل الرمز / تحميل الجلسة / التحقق من الصلاحية منفصلة)
- تقليل التبعيات الدورية
- تحسين قابلية الاختبار
القيود:
- السلوك المرئي للمستخدم لا يتغير
- واجهة API العامة تبقى مستقرة
- أعطني خطة هجرة تدريجيةحين تحصل على الخطة لا تُسارع للموافقة، صقّلها معه — هذه النقطة تُحدد نجاح إعادة الهيكلة أو فشلها:
عدّل الخطة:
- حدد الملفات المتأثرة لكل مرحلة
- أضف استراتيجية تراجع (rollback)الخطوة الثانية: تنفيذ تدريجي مع اختبار بعد كل خطوة
بعد تحديد الخطة، نفّذ مرحلةً مرحلةً، وشغّل الاختبارات بعد كل مرحلة للتأكد من عدم تغيير السلوك. قاعدة ثابتة تستحق التمسك بها:
لا تُعيد هيكلة كود بدون اختبارات تُغطيه. لو أعطيت Codex إعادة هيكلة دالة مساعدة بلا اختبارات، قد "يُحسّن" فرعًا للحالات الحدية تبدو ككود معطل لكنها تُعالج حالةً نادرة. تكتشف ذلك حين يتعطل الإنتاج.
لذا إذا لم يكن للكود اختبارات، الخطوة الأولى في إعادة الهيكلة ليست التعديل بل كتابة الاختبارات أولًا — التقاط "السلوك الحالي" كـ snapshot، وبعد إعادة الهيكلة يُقارن بها، التطابق هو النجاح.
سير عمل إعادة الهيكلة:
| الخطوة | ما تفعله | التنبيه الرئيسي |
|---|---|---|
| 1. اطلب الخطة | اطلب (أو استدعِ $plan) خطة إعادة هيكلة تدريجية | اكتب الهدف والقيود: السلوك لا يتغير، API مستقرة |
| 2. صقّل الخطة | اطلب تفصيل "الملفات المتأثرة لكل مرحلة + استراتيجية تراجع" | قسّمها لمراحل يمكن التحقق منها كل على حدة |
| 3. أضف الاختبارات | إذا لم يكن للكود اختبارات، اكتبها أولًا | التقاط "السلوك الحالي" كـ snapshot |
| 4. تنفيذ تدريجي | مرحلة مرحلة | لا تدعه يُعيد الكتابة دفعةً واحدة |
| 5. اختبار قبل وبعد | شغّل الاختبارات بعد كل مرحلة، النتائج يجب أن تطابق ما قبل | أي تغيير في السلوك توقف فورًا وتراجع |
💡 خلاصة بجملة واحدة: محور إعادة الهيكلة هو "السلوك الخارجي لا يتغير" — اطلب خطة تدريجية وصقّلها، ثم نفّذ خطوةً خطوة مع اختبار قبل وبعد؛ لا اختبارات = اكتبها أولًا، إعادة الكتابة دفعةً واحدة وغياب الاختبارات هما أكبر أسباب فشل إعادة الهيكلة.
05 كتابة الاختبارات: الأهم هو إجبار Codex على تغطية الحالات الحدية
النوع الأخير: كتابة اختبارات للكود.
Codex يُنجز ذلك بشكل طبيعي — الوثائق الرسمية تُشير إلى "اتبع الاتفاقيات الموجودة في الاختبارات الأخرى"، يتصفح ملفات الاختبار الموجودة ويكتب بنفس الإطار وأسلوب التأكيدات. لكن هناك فخ: إن لم تُنبّهه صراحةً، يميل لاختبار "الحالة العادية" فقط (happy path، أي المسار الطبيعي الذي يسير فيه كل شيء بسلاسة).
ما معنى "الحالة العادية فقط"؟ مثلًا لدالة عكس قائمة، يكتب اختبار "[1,2,3] تُعكس إلى [3,2,1]" — صحيح، لكن ماذا عن القائمة الفارغة؟ قائمة بعنصر واحد؟ تمرير null؟ هذه "الحالات الحدية (edge cases)" هي حيث تقع الأخطاء الحقيقية، وهي ما يجب على الاختبارات تغطيته فعلًا.
مثال توضيحي: اختبار تصادم السيارات الجديدة لا يكون فقط بقيادة بطيئة في خط مستقيم. الاختبارات الحقيقية القيّمة هي الاصطدام بالجدار، الكبح المفاجئ، الانقلاب، الاصطدام من الخلف — اختبار "ظروف قصوى". الأخطاء دائمًا في الحدود لا في المسار الطبيعي. جوهر كتابة الاختبارات هو إجبار Codex على اختبار هذه الحدود.
في IDE (بناءً على التحديد)
افتح الملف الذي يحتوي الدالة المستهدفة، حدّد الأسطر التي تُعرّف الدالة، واختر "Add to Codex Thread" من لوحة الأوامر لإضافتها للسياق، ثم:
اكتب اختبارات وحدة لهذه الدالة. اتبع الاتفاقيات في الاختبارات الأخرى.في CLI (تحديد الدالة والملف في التعليمات)
شغّل Codex، استخدم @ لتحديد الملف، وذكر اسم الدالة، واطلب صراحةً تغطية الحدود:
codexأضف اختبارات لدالة invert_list في @transform.ts.
غطّ المسار العادي والحالات الحدية.أهم جزء في هذا المثال من الوثائق الرسمية هو "والحالات الحدية" في النهاية — احذفها وعلى الأرجح ستحصل فقط على المسار العادي. قارن:
| ❌ سؤال ضبابي | ✅ سؤال دقيق |
|---|---|
| "اكتب اختبارات لهذه الدالة" | "اكتب اختبارات لـ invert_list في @transform.ts، المسار العادي + الحالات الحدية على وجه الخصوص: قائمة فارغة، عنصر واحد، null، قائمة ضخمة" |
| يختبر المسار العادي فقط، تغطية وهمية | يختبر المناطق الحقيقية التي تقع فيها الأخطاء |
حيلة إضافية — اطلب منه سد الثغرات: الحالات الحدية التي تُدرجها دائمًا ناقصة، دعه يُكمل:
فكّر أيضًا في أي حالات حدية أخرى لم أذكرها، وأضفها.| الخطوة | امتداد IDE | CLI |
|---|---|---|
| 1. حدد الهدف | حدد أسطر الدالة → "Add to Codex Thread" | استخدم @اسم_الملف وذكر اسم الدالة |
| 2. اطلب التوافق مع الأسلوب | "اتبع اتفاقيات الاختبارات الأخرى" | نفسه |
| 3. أجبره على تغطية الحدود | "المسار العادي + الحالات الحدية: [اذكرها]" | نفسه |
| 4. اطلب سد الثغرات | "ما الحالات الحدية التي لم أذكرها؟ أضفها" | نفسه |
| 5. شغّل | اطلب تشغيل الاختبارات وإصلاح الفاشلة | نفسه |
💡 خلاصة بجملة واحدة: لا تكتفِ بقول "اكتب اختبارات" — أجبره صراحةً على تغطية الحالات الحدية (قيمة فارغة، عنصر واحد، null، قيمة ضخمة)؛ "والحالات الحدية" هي الكلمة المفتاح في مثال الوثائق الرسمية؛ واطلب منه سد الثغرات — المسار العادي هو الأقل أهمية.
06 تطبيق عملي: إصلاح خطأ حقيقي من البداية للنهاية
الفهم النظري لا يكفي، يجب التطبيق. سنستخدم "إصلاح الخطأ" للتطبيق — خطواته الأربع هي الأكمل، وحين تتقنه تتعلم باقي الأنواع تلقائيًا. هذا الخطأ الحقيقي مخصص لك لإصلاحه.
تنبيه للمنصات:
mkdir/cdتعمل مباشرةً على Mac / Linux؛ على Windows يُفضَّل PowerShell، وأنشئcalc.pyبالمفكرة يدويًا.
الخطوة الأولى: أنشئ مشروعًا لعبةً يحتوي على خطأ
mkdir bug-demo
cd bug-demoMac / Linux:
echo 'def average(numbers):
return sum(numbers) / len(numbers)' > calc.pyWindows: أنشئ calc.py بالمفكرة، والصق هذين السطرين:
def average(numbers):
return sum(numbers) / len(numbers)تبدو دالة average صحيحة — لكن تمرير قائمة فارغة يتسبب في قسمة على صفر وانهيار. هذا هو الخطأ الذي سنصلحه.
الخطوة الثانية: شغّل Codex في الجذر
codexالخطوة الثالثة: طبّق سير عمل إصلاح الخطأ، وأعطِ وصفة إعادة الإنتاج
الخطأ: استدعاء average([]) في calc.py يتسبب في انهيار.
إعادة الإنتاج:
1) مرّر قائمة فارغة [] لدالة average
2) يظهر حتمًا ZeroDivisionError: division by zero
القيود:
- أصغر تغيير ممكن، لا تُعدّل signature الدالة.
المطلوب: أعد إنتاج الخطأ أولًا، ثم حدد السبب الجذري (لا تُعدّل بعد)، ثم أعطِ أصغر إصلاح،
وأخيرًا أضف اختبار انحدار يُعيد إنتاج الخطأ وشغّله وتأكد من نجاحه.المتوقع: سيُعيد Codex إنتاج الخطأ أولًا، ثم يُخبرك بالسبب الجذري — حين تكون القائمة فارغة len(numbers) يكون 0، والقسمة على 0 تُحدث الانهيار؛ ثم يُعطيك diff (مقارنة التغيير)، ويتوقف انتظارًا لموافقتك؛ بعد الموافقة ينشئ ملف اختبار (مثل test_calc.py) بحالة اختبار مخصصة للقائمة الفارغة.
الخطوة الرابعة: وافق على التغيير وشاهده يُشغّل التحقق
انظر للـ diff وافق بـ "نعم". سيُشغّل Codex الاختبارات التي كتبها للتو — هذا ما تعنيه الوثائق الرسمية بـ"تشغيل التحقق بعد الإصلاح".
المتوقع (بحسب إطار الاختبار لديك):
test_calc.py::test_average_empty_list PASSED
test_calc.py::test_average_normal PASSEDالاختضرار الكامل = الخطأ أُصلح وأُقفل — من يُعيد فتح نفس الأمر مستقبلًا سيتحول الاختبار للأحمر فورًا.
الخطوة الخامسة: اخرج وتأكد من التطبيق
cat calc.py(Windows: type calc.py)
المتوقع: في calc.py يظهر منطق معالجة القائمة الفارغة، ويوجد ملف اختبار في المجلد. تطابقهما مع ما وافقت عليه = اكتملت دورة إصلاح الخطأ بالكامل.
💡 خلاصة بجملة واحدة: شغّل دورة إصلاح الخطأ الكاملة — ازرع خطأ حقيقيًا، أعطِ وصفة إعادة إنتاج، دعه يُعيد الإنتاج أولًا ثم يُصلح، شاهده يكتب اختبارات ويحوّلها للأخضر؛ حين تُتقن هذا النوع، الباقية تأتي بالقياس.
07 الخلاصة
قسّم هذا الجزء 80% من عملك اليومي إلى أربعة أنواع، ولكل منها أسلوب ثابت وسير عمل قابلة للنسخ:
| النوع | جوهر سير العمل | أهم تنبيه |
|---|---|---|
| استكشاف المستودع | "البنية العامة → الكود المسؤول عن X في أي ملفات → تتبع مسار معين" | IDE يرى الملفات المفتوحة تلقائيًا، CLI يحتاج @؛ للقراءة فقط طوال الوقت |
| إصلاح خطأ | "أعطِ وصفة إعادة الإنتاج → إنتاج أولًا ثم السبب الجذري → أصغر إصلاح → تشغيل التحقق" | الوصفة أكثر قيمةً من الوصف العام، لا تُغفل التحقق |
| إعادة الهيكلة | "اطلب الخطة أولًا → صقّلها → تنفيذ تدريجي → اختبار قبل وبعد" | السلوك لا يتغير، لا اختبارات = اكتبها أولًا، لا تُعيد الكتابة دفعةً |
| كتابة الاختبارات | "مسار عادي + تركيز على الحدود، ثم اطلب سد الثغرات" | "والحالات الحدية" هي الكلمة المفتاح، لا تختبر المسار العادي فقط |
الخيط الذي يربط الأنواع الأربعة هو نفسه دائمًا: اترك لـ Codex نافذةً ليتحقق من نفسه — الاستكشاف يطلب قائمة خطوات يمكن التحقق منها، إصلاح الخطأ يُشغّل إعادة الإنتاج والاختبارات، إعادة الهيكلة تتحقق من التطابق مع اختبارات الـ snapshot، كتابة الاختبارات تُجبره على تغطية الحدود. طالما لدى Codex ما يتحقق منه، لن يتوقف عند "يبدو صحيحًا".
ما تستطيع فعله الآن: لأي نوع من الأعمال المتكررة لا تعود تقف أمام المؤشر حائرًا — استدعِ الأسلوب المقابل مباشرةً، تعلم ما تطلبه من Codex في كل خطوة وما تراقبه أنت، وتعلم الفارق بين IDE وCLI لكل نوع. هذه الأساليب الأربعة هي السقالة لغالبية عملك؛ حين تألفها ستجد أن أكثر المهام تعقيدًا ما هي إلا مزيج وتسلسل لهذه الأنواع الأربعة.
الجزء التالي 15 · الصلاحيات، الحاوية الرملية والموافقات — في هذا الجزء صادفت مرات عدة "توقف قبل الموافقة" و"التبديل للقراءة فقط" لكن الآلية الكاملة لم تُشرح بعد. كيف يعرف Codex ما يحتاج موافقة وما يُمرّر تلقائيًا؟ ما حدود الحاوية الرملية؟ الجزء التالي يكشف الصلاحيات، الحاوية الرملية، والموافقات دفعةً واحدة.