تحتاج إلى نقل الـ repo كله من moment إلى date-fns، أو إعادة تسمية API مستخدَم في 80 موضعًا، أو ترحيل كل component إلى نمط جديد. على نطاق المؤسسة هذا هو التغيير الذي يمتدّ عبر عشرات الملفات ويعبر كود عدة فرق — التغيير القابع في الـ backlog منذ ربع سنة لأن لا أحد يريد تولّي الـ find-and-replace. إنه عمل واسع ومملّ وعرضة للأخطاء — تمامًا النوع الذي يؤدّيه البشر بسوء ويتخطّون فيه خطوات. هنا يتألّق الـ agent: يؤدّي الـ 90% الميكانيكية بإتقان، والأهم أنه يسلّمك قائمة بالـ 10% التي تحتاج قرارًا حقيقيًا بدل أن يخمّن بصمت.
- الـ before/after بالضبط: الشيء القديم، والشيء الجديد، ومثال واحد حوّلته أنت يدويًا سلفًا كي يكون لدى Claude هدفٌ يطابقه.
- مجلد المشروع مفتوحًا في Claude Desktop، وgit working tree نظيف، وtest suite ناجح — تريد أن ترى الـ migration كـ diff قابل للمراجعة وأن تُثبت أنه لم يكسر شيئًا.
- أي استثناءات معروفة — مواضع لا ينبغي لها التغيّر بحقّ — كي تُذكَر صراحةً منذ البداية.
-
امسح blast radius أولًا
افتح مجلد المشروع في Claude Desktop واسأل في المحادثة — مسح repo لا يحتاج Terminal. قبل تغيير أي شيء، احصل على الجرد الكامل: تريد معرفة حجم العمل وشكله — ورصد الاستخدامات الغريبة — قبل أي تعديل واحد.
أنت تطلبنحن ننتقل من `moment` إلى `date-fns`. اعثر على كل استخدام عبر الـ repo وجمّعها: التحويلات المباشرة واحدة بواحدة، وتلك التي لا مكافئ نظيف لها، وأي شيء غير معتاد. أعطني الأعداد وقائمة الملفات. لا تغيّر شيئًا بعد.ما تحصل عليه جردٌ مجمَّع — «62 استدعاء
.format()بسيط، و9 تستخدم ميزة بلا مكافئ مباشر، و3 تفعل شيئًا غريبًا بالـ timezones» — كي تعرف ما ستواجهه قبل أن تلتزم.استعِن بـ subagent في المسح إن كان الـ repo كبيرًا، كي لا يزاحم البحث الواسع الـ context الذي تحتاجه للـ migration نفسها. انظر
/features/subagents/. -
حوّل الأغلبية الميكانيكية
الآن نفّذ الـ 90% المملّة — الاستبدالات النظيفة واحدة بواحدة — واترك الحالات الصعبة دون مساس ومُعلَّمة. طابِق مثالك المحوَّل يدويًا بالضبط. تعود المسحة على شكل diff مرئي في Claude Desktop؛ تصفّحه في لوحة الملفات واقبله قبل المضيّ قدمًا.
أنت تطلبحوّل كل الحالات المباشرة لتطابق هذا المثال الذي أنجزته يدويًا: [الصق مثالك المحوَّل]. اترك تلك التي لا مكافئ نظيف لها دون مساس، لكن علّم كلًّا منها بتعليق `// TODO: migrate manually —` يشرح السبب. أرني الـ diff.ما تحصل عليه diff كبير وميكانيكي يغطّي الحالات السهلة، مع ترك الصعبة حقًّا في مكانها ومُوسومة لك بوضوح — لا مشوّهة بصمت كي تُكمل الـ migration.
-
قرّروا الحالات الصعبة معًا
راجع القلّة المُعلَّمة. هذا هو الجزء الذي يحتاج حُكمك فعلًا — Claude يعرض الخيارات، وأنت تتّخذ القرار.
أنت تطلباشرح لي كل حالة `TODO: migrate manually`. لكلٍّ منها، أرني الكود القديم، واشرح لماذا لا مكافئ نظيف لها، وأعطني أفضل خيارين مع المقايضة. سأقرّر كلًّا منها.ما تحصل عليه قائمة قرارات قصيرة، حالةً بحالة — الكود القديم، ولماذا هي شائكة، وخيارات حقيقية — كي ينال الـ 10% الصعبة حُكمًا بشريًا بدل تخمين واثق.
-
أثبتها بالـ suite وبـ diff نظيف
شغّل الـ tests، ثم اقرأ الـ diff كاملًا. migration تجعل الـ suite أخضر وتُقرأ بنظافة هي التي تستطيع فعلًا عمل merge لها. تشغيل الـ suite هو شقّ مسار
Power Track(جلسة مفعّلة للـ Terminal)؛ إن لم تكن لديك واحدة، شغّله بنفسك والصق أي كسر في محادثة Claude Desktop.أنت تطلبشغّل الـ test suite كاملًا. أصلِح أي شيء كسرته الـ migration، ثم أعطني الـ diff الكامل لمراجعته في كُتل منطقية — التحويلات الميكانيكية منفصلة عن القرارات اليدوية.ما تحصل عليه suite أخضر وdiff مقسَّم إلى «المسحة المملّة» و«القرارات»، كي تكون المراجعة سريعة وترى بالضبط أين طُبِّق الحُكم.
- codemod بدلًا من ذلك (مسار `Power Track`): لـ repo هائل حقًّا، اطلب من Claude أن يكتب codemod / script يؤدّي التحويل، وشغّله على عيّنة، وراجع الـ script — أحيانًا تحويل قابل للمراجعة أفضل من 500 تعديل منفرد. كتابة الـ script وتشغيله حركة مفعّلة للـ Terminal (مسار
Power Track)؛ أما مسار التعديل المباشر أعلاه فيبقى بالكامل على Claude Desktop. - إطلاق مرحلي: رحّل module واحدًا، واجعله أخضر ومراجَعًا، ثم قل «الآن نفّذ المثل عبر الباقي بنفس الطريقة» — كي يُثبَت النمط قبل أن يكون في كل مكان. قسّم الـ commits (انظر playbook الـ git-workflow): المسحة المملّة في commit، والحالات المقرَّرة يدويًا في آخر، كي يبقى الـ diff قابلًا للمراجعة بدل أن يصل جدارًا واحدًا غير مفصول.
- مسحة واحدة داخل إعادة بناء أكبر: هذا الـ playbook هو ابن العمّ الميكانيكي لـ modernize-subsystem — هذا مسحة واحدة مملّة ومحدّدة جيدًا (استبدال الـ library، إعادة تسمية الـ API)؛ وذاك ينسّق تحديثًا كاملًا متعدد الخطوات عبر subsystem. حين تكون الـ migration حركةً واحدة في مسار أكبر، شغّلها هنا للمسحة نفسها ودَع modernize-subsystem يرتّب المسار من حولها.
- قائمة الحالات التي «تعذّر تحويلها تلقائيًا» هي أهم مُخرَج — اقرأها بعناية. هناك بالضبط تختبئ القرارات الحقيقية (والـ bugs الدقيقة)، فهي الجزء الذي لا تتصفّحه مرورًا. والنطاق الواسع لا يمنح المسحة إعفاءً: التغيير الواسع يُقرأ ويُختبَر أخضر قبل أن يَنزل — السعة ليست عذرًا لعمل merge لـ diff لم يراجعه أحد. واستعِن بـ subagent في المسح كي لا يزاحم حجم العمل الهائل الـ migration نفسها خارج الـ context — انظر
/features/subagents/. - لا تدعه يدّعي أنه «رحّل كل شيء» عبر دفع الحالات الصعبة بهدوء إلى شيء يُترجَم (compiles) لكنه يتصرّف على نحو مختلف. اجعله يُعلِّم، لا يخمّن.
- نفّذها على tree نظيف كي تكون الـ migration diff قابلًا للمراجعة. تغيير ضخم مخلوط بتعديلات غير ذات صلة يستحيل مراجعته وخطِرٌ عمل merge له.
ستحصل في النهاية على التغيير الواسع الذي كنت تتهيّبه يكتمل في مسحة واحدة — الـ 90% الميكانيكية محوَّلة ومُختبَرة، والـ 10% الشائكة مُظهَرة ومقرَّرة بحُكمك — بدل أسبوع من find-and-replace عرضة للأخطاء.
أسئلة يطرحها الناس
- ما الذي أحتاج تجهيزه قبل البدء في الـ migration؟
- ثلاثة أشياء: الـ before/after بالضبط (الشيء القديم، والشيء الجديد، ومثال واحد حوّلته أنت يدويًا)، وgit working tree نظيف، وtest suite ناجح. المسح ومسحة التحويل يجريان بالكامل في Claude Desktop كديفات مرئية تقبلها في لوحة الملفات؛ وحده تشغيل الـ test suite في النهاية خطوة في مسار `Power Track`. الـ working tree النظيف ضروري لأن الـ migration يجب أن تظهر كـ diff واحد قابل للمراجعة — لا مدفونًا في تعديلات غير ذات صلة.
- كيف أمنع Claude من تشويه الحالات الصعبة بصمت كي يدّعي اكتمال الـ migration؟
- قل له صراحةً أن يترك الحالات التي لا مكافئ نظيف لها دون مساس ويُعلّم كلًّا منها بتعليق `// TODO: migrate manually —` يشرح السبب. تعليمة «لا تدعه يدّعي رحّل كل شيء» هي التعليمة الحاسمة هنا — قائمة الحالات المُعلَّمة هي أهم مخرجات هذا الـ workflow كله.
- كم يستغرق الـ migration النموذجي لـ repo كامل؟
- خطوة المسح تستغرق بضع دقائق؛ مسحة التحويل الميكانيكية تعتمد على حجم الـ repo لكنها تعمل عادةً في أقل من 10 دقائق. ضع في حسبانك 45 دقيقة إجمالًا — معظمها للمسح ومراجعتك للحالات الصعبة المُعلَّمة وتشغيل الـ tests، لا للتحويل نفسه.
- هل يمكنني تكييف هذا لكتابة codemod script بدل التعديلات المباشرة؟
- نعم — لـ repo ضخم حقًّا، اطلب من Claude كتابة codemod أو script يؤدّي التحويل، وشغّله على عيّنة أولًا، وراجع الـ script نفسه. التحويل الواحد القابل للمراجعة أكثر أمانًا في الغالب من مئات التعديلات المنفردة، وهو قابل لإعادة التشغيل إن تغيّر الـ repo قبل الـ merge.