نما ملفٌ حتى صار فوضى — function من 400 سطر، ومنطق مكرّر، وأسماء تكذب. إنه الملف الذي يتفاداه الجميع في الفريق بهدوء: أهمّ من أن يُحذف، وأكثر تشابكًا من أن يُمَسّ، فتتراكم الحلول الالتفافية بدلًا من إصلاحه. تريده أنظف، لكن «refactor» بلا شبكة أمان ليس إلا «أعد الكتابة وادعُ». هذا النظام يجعل الـ test suite حزام الأمان: أخضر قبل، أخضر بعد، والتغيير البنيوي بينهما — كي يصير «لم أغيّر الـ behaviour» حقيقةً أثبتّها، لا أملًا تحمله.
- الملف الذي تريد عمل refactor له — افتح مجلد المشروع في Claude Desktop وأشِر إليه في المحادثة.
- test suite ناجح يغطّي الكود — إن لم يوجد، شغّل playbook الـ backfill-tests أولًا. لا بدّ أن يوجد حزام الأمان قبل أن تنطلق.
- أمر الـ test، كي يستطيع Claude تشغيله قبل وبعد ويُريك النتيجتين معًا — تشغيله خطوة في مسار
Power Track(جلسة مفعّلة للـ Terminal)؛ وإن شئت، شغّله بنفسك والصق النتيجتين.
-
أثبت الأخضر، ثم سمِّ الـ code smells
أثبت أن الحالة الابتدائية خضراء أولًا — تلك هي خط الأساس (baseline) لديك (شقّ تشغيل الـ suite هو جزء
Power Track؛ والباقي مجرّد محادثة في Claude Desktop). ثم احصل على خطة لـ ما ستغيّره قبل أن يتحرّك أي كود.أنت تطلبأولًا شغّل الـ test suite وأكّد أنه أخضر — هذا خط الأساس لدينا. ثم اقرأ هذا الملف وأخبرني بأكبر ثلاث مشكلات بنيوية وكيف ستُصلح كلًّا منها، بالترتيب، بلا تغيير في الـ behaviour. لا تعمل refactor بعد.ما تحصل عليه خط أساس أخضر مؤكَّد، بالإضافة إلى خطة قصيرة مرتّبة — «استخرج الـ validation إلى function خاصّة بها، اطوِ الفروع المكرّرة، أعد تسمية
dataإلى ما تحمله فعلًا» — وكلها behaviour-preserving.تصحيح مقاربة خاطئة في نثر أرخص بكثير من تصحيحها في diff من 300 سطر. اقرأ الخطة قبل أن يكتب سطرًا.
-
نفّذ الـ refactor بحركات صغيرة قابلة للمراجعة
نفّذ التغييرات كخطوات منفصلة، لا كإعادة كتابة واحدة عملاقة — كي تعرف بالضبط أي حركة كسرت شيئًا إن انكسر. في Claude Desktop تعود كل خطوة على شكل diff مرئي تقبله أو ترفضه في لوحة الملفات، وهذه بالضبط المراجعة خطوةً بخطوة التي تريدها هنا.
أنت تطلبنفّذ الـ refactor كخطوات صغيرة منفصلة بالترتيب الذي اتّفقنا عليه. يجب ألّا يتغيّر الـ behaviour. بعد كل خطوة، أرني الـ diff لتلك الخطوة كي أتابع ما تحرّك.ما تحصل عليه سلسلة من diffs مركّزة — استخراج، ثم إزالة تكرار، ثم إعادة تسمية — كلٌّ منها سهل القراءة وقابل للقبول واحدًا تلو الآخر، بدل جدار واحد من التغييرات لا يمكن مراجعته.
-
أثبت أن الـ behaviour لم يتغيّر
شغّل الـ suite نفسه مجددًا. الأخضر ذاته هو كل المقصد — إنه الفرق بين «عملت refactor» و«أعدت الكتابة وأملت».
أنت تطلبشغّل الـ suite كاملًا مجددًا وأرني النتيجة إلى جانب خط الأساس. إن كان أي شيء أحمر، فذلك تغيير في الـ behaviour — تراجع عن تلك الخطوة وأخبرني بما لمسته. لا تُموّه على فشل.ما تحصل عليه الأخضر ذاته الذي بدأت منه. إن صار test أحمر، فاعتراف صادق «الخطوة 2 غيّرت الـ behaviour هنا» وتراجع — لا test مُعدَّل بهدوء كي يمرّ.
لا تأخذ «الـ behaviour لم يتغيّر» على عواهنه أبدًا — إعادة تشغيل الـ suite هي ما يجعله صحيحًا. إعادة تشغيله هي شقّ
Power Track؛ إن شغّلت خط الأساس بنفسك، فشغّله ثانيةً بنفسك والصق النتيجة كي تكون مقارنة القبل/البعد صادقة. -
اشرح لي ما تغيّر ولماذا
اختم بسرد قصير كي يفهم مراجعك المستقبلي (وأنت في المستقبل) النيّة وراء الـ diff.
أنت تطلبلخّص ما غيّرته ولماذا، في بضع نقاط أستطيع لصقها في وصف الـ PR — ما الذي صار أنظف الآن وأي behaviour بقي مطابقًا تمامًا.ما تحصل عليه changelog محكَم تستطيع وضعه مباشرةً في الـ PR، كي يقرأ المراجع النيّة، لا مجرد diff.
- لا suite بعد: لا تعمل refactor دون رؤية واضحة. شغّل playbook الـ backfill-tests لإضافة characterization tests أولًا، ثم عُد إلى هنا — تأسيس الـ suite شرطٌ مسبق، لا إحماءٌ اختياري.
- جزء من تحديث أكبر: الـ refactor الآمن هو الحركة الأساسية داخل إعادة بناء كبيرة — حين تُحدّث subsystem كاملًا، يكون كل تنظيف behaviour-preserving هنا خطوةً واحدة قابلة للمراجعة في ذلك المسار. انظر playbook الـ modernize-subsystem للتنسيق العام؛ وهذا الـ playbook هو كيف تبقى كل حركة منفردة صادقة. behaviour-preserving يعني مع ذلك أنك تقرأ الـ diff — أنت author of record على كل خطوة.
- إعادة تشكيل أكبر: لتغيير بنيوي عبر عدة ملفات، اطلب الخطة في plan mode أولًا واعتمدها قبل أي تعديلات — انظر
/features/plan-mode/.
- الـ green suite حزام أمانك — فاربِطه فعلًا. اجعل Claude يُشغّل الـ tests قبل وبعد؛ لا تأخذ كلامه أن الـ behaviour لم يتغيّر أبدًا، فـ«يبدو مكافئًا» و«هو مكافئ» ادّعاءان مختلفان، وإعادة التشغيل وحدها تُثبت الثاني. التشغيلان الأخضران هما كامل ضمان الأمان — لا تتجاوز أيًّا منهما. وإن كانت التغطية ضعيفة، فلا حزام أمان لديك بعد: شغّل playbook الـ backfill-tests أولًا، ثم عُد.
- إن اقترح تغييرًا في الـ behaviour «ما دمنا هنا»، فتوقّف وافصله. خلط refactor بتغيير في الـ behaviour يعني أن test أحمر قد يكون أيًّا منهما، وتكون قد فقدت حزام الأمان.
- لا تدعه يعدّل test كي يُخفي فشل refactor. test أحمر بعد تغيير behaviour-preserving إشارةٌ حقيقية — أنصِت إليها.
ستحصل في النهاية على ملف متشابك يصير نظيفًا، مع الـ green suite ذاته يُثبت أن الـ behaviour لم يتحرّك قط — refactor تستطيع الدفاع عنه في المراجعة بدل إعادة كتابة تشعر حيالها بقلق صامت.
أسئلة يطرحها الناس
- هل أحتاج إلى test suite موجود قبل استخدام هذا الـ playbook؟
- نعم — الـ test suite هو ضمان الأمان بأكمله. إن لم يكن الكود مُغطّى، شغّل playbook الـ `backfill-tests` أولًا لإضافة characterization tests، ثم عُد إلى هنا. الـ refactor بلا suite لتشغيله قبل وبعد ليس إلا إعادة كتابة باسم ألطف. القراءة والتخطيط وديفات الـ refactor كلها تجري في Claude Desktop؛ وحده تشغيل الـ suite قبل وبعد خطوة في مسار `Power Track` (جلسة مفعّلة للـ Terminal، أو تشغّله بنفسك وتلصق النتيجتين).
- ماذا أفعل إن صار test أحمر بعد الـ refactor؟
- هذا النظام يعمل كما يجب، لا فشل فيه. test أحمر بعد تغيير behaviour-preserving إشارة حقيقية — اطلب من Claude تحديد أي خطوة بالضبط أحدثته، والتراجع عن تلك الخطوة، وإعادة النظر في المقاربة. لا تسمح له أبدًا بتعديل الـ test لإخفاء الفشل.
- كيف أمنع Claude من إدخال تغييرات في الـ behaviour أثناء الـ refactor؟
- حارسان: اطلب الخطة في نثر أولًا واقرأها قبل أن يتحرّك أي كود، ثم اطلب كل تغيير كـ diff صغير منفصل كي ترى بالضبط ما أحدثته كل خطوة. إن اقترح أي وقت تغييرًا في الـ behaviour «ما دمنا هنا»، فتوقّف وافصله إلى PR مستقل.
- هل يمكنني استخدام هذا لتغيير بنيوي يمتدّ عبر عدة ملفات لا ملف واحد؟
- لإعادة تشكيل متعددة الملفات، استخدم plan mode أولًا — اطلب الخطة الكاملة ووافِق عليها قبل أي تعديلات. النسخة أحادية الملف من هذا الـ playbook تفترض نطاقًا محدودًا؛ إعادات التشكيل الكبيرة تحتاج بوّابة الموافقة الإضافية التي يوفّرها plan mode.