تجاوز إلى المحتوى
تعلّم لعملك المرجع مقالات المحفوظات
العربية

playbook

نفّذ refactor بأمان خلف green suite

نظّف ملفًا متشابكًا بلا تغيير في الـ behaviour — مستخدمًا الـ test suite كحزام أمان، تُشغّله قبل وبعد كي تُثبت أن شيئًا لم يُكسَر بدل أن تأمل ذلك.

متوسّط ~30 دقيقة

متى تلجأ إلى هذا

نما ملفٌ حتى صار فوضى — function من 400 سطر، ومنطق مكرّر، وأسماء تكذب. تريده أنظف، لكن «refactor» بلا شبكة أمان ليس إلا «أعد الكتابة وادعُ». هذا النظام يجعل الـ test suite حزام الأمان: أخضر قبل، أخضر بعد، والتغيير البنيوي بينهما — كي يصير «لم أغيّر الـ behaviour» حقيقةً أثبتّها، لا أملًا تحمله.

جهّز هذا أولًا

  • الملف الذي تريد عمل refactor له، مفتوحًا في الـ repo.
  • test suite ناجح يغطّي الكود — إن لم يوجد، شغّل playbook الـ *backfill-tests* أولًا. لا بدّ أن يوجد حزام الأمان قبل أن تنطلق.
  • أمر الـ test، كي يستطيع Claude تشغيله قبل وبعد ويُريك النتيجتين معًا.

الـ workflow

  1. أثبت الأخضر، ثم سمِّ الـ code smells

    أثبت أن الحالة الابتدائية خضراء أولًا — تلك هي خط الأساس (baseline) لديك. ثم احصل على خطة لـ *ما* ستغيّره قبل أن يتحرّك أي كود.

    أنت تطلب 
    أولًا شغّل الـ test suite وأكّد أنه أخضر — هذا خط الأساس لدينا. ثم اقرأ هذا الملف وأخبرني بأكبر ثلاث مشكلات بنيوية وكيف ستُصلح كلًّا منها، بالترتيب، بلا تغيير في الـ behaviour. لا تعمل refactor بعد.

    ما تحصل عليه خط أساس أخضر مؤكَّد، بالإضافة إلى خطة قصيرة مرتّبة — «استخرج الـ validation إلى function خاصّة بها، اطوِ الفروع المكرّرة، أعد تسمية data إلى ما تحمله فعلًا» — وكلها behaviour-preserving.

    تصحيح مقاربة خاطئة في نثر أرخص بكثير من تصحيحها في diff من 300 سطر. اقرأ الخطة قبل أن يكتب سطرًا.

  2. نفّذ الـ refactor بحركات صغيرة قابلة للمراجعة

    نفّذ التغييرات كخطوات منفصلة، لا كإعادة كتابة واحدة عملاقة — كي تعرف بالضبط أي حركة كسرت شيئًا إن انكسر.

    أنت تطلب 
    نفّذ الـ refactor كخطوات صغيرة منفصلة بالترتيب الذي اتّفقنا عليه. يجب ألّا يتغيّر الـ behaviour. بعد كل خطوة، أرني الـ diff لتلك الخطوة كي أتابع ما تحرّك.

    ما تحصل عليه سلسلة من diffs مركّزة — استخراج، ثم إزالة تكرار، ثم إعادة تسمية — كلٌّ منها سهل القراءة، بدل جدار واحد من التغييرات لا يمكن مراجعته.

  3. أثبت أن الـ behaviour لم يتغيّر

    شغّل الـ suite نفسه مجددًا. الأخضر ذاته هو كل المقصد — إنه الفرق بين «عملت refactor» و«أعدت الكتابة وأملت».

    أنت تطلب 
    شغّل الـ suite كاملًا مجددًا وأرني النتيجة إلى جانب خط الأساس. إن كان أي شيء أحمر، فذلك تغيير في الـ behaviour — تراجع عن تلك الخطوة وأخبرني بما لمسته. لا تُموّه على فشل.

    ما تحصل عليه الأخضر ذاته الذي بدأت منه. إن صار test أحمر، فاعتراف صادق «الخطوة 2 غيّرت الـ behaviour هنا» وتراجع — لا test مُعدَّل بهدوء كي يمرّ.

    لا تأخذ «الـ behaviour لم يتغيّر» على عواهنه أبدًا — إعادة تشغيل الـ suite هي ما يجعله صحيحًا.

  4. اشرح لي ما تغيّر ولماذا

    اختم بسرد قصير كي يفهم مراجعك المستقبلي (وأنت في المستقبل) النيّة وراء الـ diff.

    أنت تطلب 
    لخّص ما غيّرته ولماذا، في بضع نقاط أستطيع لصقها في وصف الـ PR — ما الذي صار أنظف الآن وأي behaviour بقي مطابقًا تمامًا.

    ما تحصل عليه changelog محكَم تستطيع وضعه مباشرةً في الـ PR، كي يقرأ المراجع النيّة، لا مجرد diff.

اجعله ملكك

  • **لا suite بعد:** لا تعمل refactor على العمياء. شغّل playbook الـ *backfill-tests* لإضافة characterization tests أولًا، *ثم* عُد إلى هنا.
  • **إعادة تشكيل أكبر:** لتغيير بنيوي عبر عدة ملفات، اطلب الخطة في plan mode أولًا واعتمدها قبل أي تعديلات — انظر /features/plan-mode/.

انتبه إلى

  • refactor بلا تشغيل test قبل وبعد هو إعادة كتابة باسم ألطف. التشغيلان الأخضران هما كامل ضمان الأمان — لا تتجاوز أيًّا منهما.
  • إن اقترح تغييرًا في الـ behaviour «ما دمنا هنا»، فتوقّف وافصله. خلط refactor بتغيير في الـ behaviour يعني أن test أحمر قد يكون أيًّا منهما، وتكون قد فقدت حزام الأمان.
  • لا تدعه يعدّل test كي يُخفي فشل refactor. test أحمر بعد تغيير behaviour-preserving إشارةٌ حقيقية — أنصِت إليها.

ستحصل في النهاية على ملف متشابك يصير نظيفًا، مع الـ green suite ذاته يُثبت أن الـ behaviour لم يتحرّك قط — refactor تستطيع الدفاع عنه في المراجعة بدل إعادة كتابة تشعر حيالها بقلق صامت.