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

playbook

نفّذ migration واسعة ومملّة بلا أن تكسر شيئًا

التغيير الذي يعمّ الـ repo والذي كنت تتهيّبه — استبدال library، إعادة تسمية API، ترقية نمط عبر 80 ملفًا — منجَزًا في مسحة واحدة، مع قائمة واضحة بالحالات التي لم يستطع تحويلها واحدة بواحدة كي تقرّرها أنت يدويًا.

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

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

تحتاج إلى نقل الـ repo كله من moment إلى date-fns، أو إعادة تسمية API مستخدَم في 80 موضعًا، أو ترحيل كل component إلى نمط جديد. إنه واسع ومملّ وعرضة للأخطاء — تمامًا العمل الذي يؤدّيه البشر بسوء ويتخطّون فيه خطوات. هنا يتألّق الـ agent: يؤدّي الـ 90% الميكانيكية على الكمال، والأهم أنه يسلّمك قائمة بالـ 10% التي تحتاج قرارًا حقيقيًا بدل أن يخمّن بصمت.

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

  • الـ before/after بالضبط: الشيء القديم، والشيء الجديد، ومثال واحد حوّلته أنت يدويًا سلفًا كي يكون لدى Claude هدفٌ يطابقه.
  • git working tree نظيف وtest suite ناجح — تريد أن *ترى* الـ migration كـ diff قابل للمراجعة وأن تُثبت أنه لم يكسر شيئًا.
  • أي استثناءات معروفة — مواضع لا ينبغي لها التغيّر بحقّ — كي تُذكَر صراحةً منذ البداية.

الـ workflow

  1. امسح blast radius أولًا

    قبل تغيير أي شيء، احصل على الجرد الكامل. تريد معرفة حجم العمل وشكله — ورصد الاستخدامات الغريبة — قبل أي تعديل واحد.

    أنت تطلب 
    نحن ننتقل من `moment` إلى `date-fns`. اعثر على كل استخدام عبر الـ repo وجمّعها: التحويلات المباشرة واحدة بواحدة، وتلك التي لا مكافئ نظيف لها، وأي شيء غير معتاد. أعطني الأعداد وقائمة الملفات. لا تغيّر شيئًا بعد.

    ما تحصل عليه جردٌ مجمَّع — «62 استدعاء .format() بسيط، و9 تستخدم feature بلا مكافئ مباشر، و3 تفعل شيئًا غريبًا بالـ timezones» — كي تعرف ما ستواجهه قبل أن تلتزم.

    استعِن بـ subagent في المسح إن كان الـ repo كبيرًا، كي لا يزاحم البحث الواسع الـ context الذي تحتاجه للـ migration نفسها. انظر /features/subagents/.

  2. حوّل الأغلبية الميكانيكية

    الآن نفّذ الـ 90% المملّة — الاستبدالات النظيفة واحدة بواحدة — واترك الحالات الصعبة دون مساس ومُعلَّمة. طابِق مثالك المحوَّل يدويًا بالضبط.

    أنت تطلب 
    حوّل كل الحالات المباشرة لتطابق هذا المثال الذي أنجزته يدويًا: [الصق مثالك المحوَّل]. اترك تلك التي لا مكافئ نظيف لها دون مساس، لكن علّم كلًّا منها بتعليق `// TODO: migrate manually —` يشرح السبب. أرني الـ diff.

    ما تحصل عليه diff كبير وميكانيكي يغطّي الحالات السهلة، مع ترك الصعبة حقًّا في مكانها ومُوسومة لك بوضوح — لا مشوّهة بصمت كي تُكمل الـ migration.

  3. قرّروا الحالات الصعبة معًا

    راجع القلّة المُعلَّمة. هذا هو الجزء الذي يحتاج حُكمك فعلًا — Claude يعرض الخيارات، وأنت تتّخذ القرار.

    أنت تطلب 
    اشرح لي كل حالة `TODO: migrate manually`. لكلٍّ منها، أرني الكود القديم، واشرح لماذا لا مكافئ نظيف لها، وأعطني أفضل خيارين مع المقايضة. سأقرّر كلًّا منها.

    ما تحصل عليه قائمة قرارات قصيرة، حالةً بحالة — الكود القديم، ولماذا هي شائكة، وخيارات حقيقية — كي ينال الـ 10% الصعبة حُكمًا بشريًا بدل تخمين واثق.

  4. أثبتها بالـ suite وبـ diff نظيف

    شغّل الـ tests، ثم اقرأ الـ diff كاملًا. migration تجعل الـ suite أخضر وتُقرأ بنظافة هي التي تستطيع فعلًا عمل merge لها.

    أنت تطلب 
    شغّل الـ test suite كاملًا. أصلِح أي شيء كسرته الـ migration، ثم أعطني الـ diff الكامل لمراجعته في كُتل منطقية — التحويلات الميكانيكية منفصلة عن القرارات اليدوية.

    ما تحصل عليه suite أخضر وdiff مقسَّم إلى «المسحة المملّة» و«القرارات»، كي تكون المراجعة سريعة وترى بالضبط أين طُبِّق الحُكم.

اجعله ملكك

  • **codemod بدلًا من ذلك:** لـ repo هائل حقًّا، اطلب من Claude أن *يكتب codemod / script* يؤدّي التحويل، وشغّله على عيّنة، وراجع الـ script — أحيانًا تحويل قابل للمراجعة أفضل من 500 تعديل منفرد.
  • **إطلاق مرحلي:** رحّل module واحدًا، واجعله أخضر ومراجَعًا، ثم قل «الآن نفّذ المثل عبر الباقي بنفس الطريقة» — كي يُثبَت النمط قبل أن يكون في كل مكان.

انتبه إلى

  • قائمة الحالات التي «تعذّر تحويلها تلقائيًا» هي أهم مُخرَج — راجعها بعناية. هناك بالضبط تختبئ القرارات الحقيقية (والـ bugs الدقيقة).
  • لا تدعه يدّعي أنه «رحّل كل شيء» عبر دفع الحالات الصعبة بهدوء إلى شيء يُترجَم (compiles) لكنه يتصرّف على نحو مختلف. اجعله يُعلِّم، لا يخمّن.
  • نفّذها على tree نظيف كي تكون الـ migration diff قابلًا للمراجعة. تغيير ضخم مخلوط بتعديلات غير ذات صلة يستحيل مراجعته وخطِرٌ عمل merge له.

ستحصل في النهاية على التغيير الواسع المتهيَّب يهبط في مسحة واحدة — الـ 90% الميكانيكية محوَّلة ومُختبَرة، والـ 10% الشائكة مُظهَرة ومقرَّرة بحُكمك — بدل أسبوع من find-and-replace عرضة للأخطاء.