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

playbook

انضمّ إلى codebase غريب وأطلِق أول إصلاح لك

القوس الكامل — أسبوعك الأول على repo لم تره من قبل، وbug في الـ production، وكاتبه رحل منذ زمن — وصولًا إلى إصلاح مُراجَع ومُختبَر تفهمه. الكبير الذي يربط كل playbook هندسي آخر معًا.

متقدّم ~نصف يوم

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

وظيفة جديدة، الأسبوع الأول. هناك bug في الـ production، ومن كتب الـ auth flow غادر قبل شهرين، والـ README متأخّر بثلاث إعادات كتابة. عادةً هذا يومٌ من الـ grep، ويومٌ من التخمين، وcommit لست واثقًا منه. هذا النظام يمشي القوس كاملًا — اقرأ الـ repo، شخّص من الأدلّة، أصلِح بـ test يُثبت الإصلاح، وcommit بنظافة — كي تبقى أنت المهندس ويكون Claude القارئ السريع والشريك الذي لا يكلّ. إنه يجمع playbooks القراءة والـ debug والـ test والـ commit في حركة واحدة.

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

  • Claude Code مفتوحًا في المجلد الجذر للمشروع، كي يقرأ ملفاتك الفعلية — لا ذاكرته عن شكل الـ repos المشابهة عادةً.
  • تقرير الـ bug، وإن وُجد، الـ stack trace **الكامل** مع طريقة لإعادة إنتاجه.
  • working tree نظيفة، وأوامر الـ test suite والـ type-checker والـ linter — كي يستطيع Claude تشغيل الـ loop الحقيقي لديك ورؤية اللون الأحمر.

الـ workflow

  1. احصل على الخريطة قبل أن تبدأ المطاردة

    لا تنقضّ على الـ bug على البارد. أنفِق عشر دقائق في التوجّه كي تكون تُصحِّح بنموذج للنظام، لا بمصباح يدوي في الظلام.

    أنت تطلب 
    اقرأ هذا الـ repo وأعطني الخريطة: الـ modules العليا، وكيف يتدفّق request من الـ route إلى الـ database، وأين يعيش الـ authentication. بالإنجليزية البسيطة، سمِّ الملفات الحقيقية — لا تعطني محاضرة عامة عن الـ framework.

    ما تحصل عليه جولة راسخة — src/routes/ ← middleware/auth.ts ← الـ session store — مسمّيةً ملفات موجودة. الآن تعرف أين تضع يديك.

    إن وصف نسخة عامة من الـ framework الخاص بك بدل ملفاتك الفعلية، فهو لم يقرأ الـ repo. تأكّد أنك فتحت Claude Code في المجلد الجذر للمشروع.

  2. شخّص الـ bug من الأدلّة، مُرتَّبًا

    الآن وجّهه إلى العَرَض مع الـ trace، واطلب قائمة فرضيّات مرتّبة *قبل* أي إصلاح. أنت تريد فحص المنطق وهو ما زال رخيصًا.

    أنت تطلب 
    يبلّغ المستخدمون أنه يُسجَّل خروجهم عشوائيًا. هذا هو الـ stack trace الكامل. تعقّب منطق انتهاء صلاحية الـ session من البداية للنهاية وأعطني الأسباب الثلاثة الأرجح، مرتّبةً، مع الملف والسطر لكلٍّ منها والمنطق وراءه. لا تُصلِح أي شيء بعد.

    ما تحصل عليه قائمة مرتّبة بمؤشّرات بنمط auth/session.ts:142 ومع سبب كلٍّ — TTL قديم، أو race على الـ refresh، أو فحص انحراف ساعة (clock-skew) — كي تُصحِّح من الأدلّة، لا من الحدس.

    «لا تُصلِح أي شيء بعد» هي العبارة الحاملة للأثقال. التشخيص هو الجزء الأحوج إلى حُكمك أنت قبل أن يتغيّر أي كود.

  3. أصلحه، واجعله يُثبت نفسه بـ test

    بمجرد أن تؤكّد السبب، اطلب الـ test الذي يفشل ثم ينجح إلى جانب الإصلاح. الـ test من الأحمر إلى الأخضر هو دليلك على أن الإصلاح حقيقي.

    أنت تطلب 
    السبب رقم 2 صحيح. أصلحه، وأضِف test يفشل على السلوك القديم وينجح على الجديد. أرِني الـ diff قبل أن تلمس أي شيء آخر.

    ما تحصل عليه تغيير محكَم إضافةً إلى regression test يُعيد إنتاج الـ bug فعلًا — وdiff تقرأه سطرًا سطرًا قبل الموافقة. الـ test هو الإيصال على أن الإصلاح يعالج الـ bug، لا مجرّد العَرَض الذي وصفته.

  4. شغّل الـ loop الحقيقي لديك واقرأ كل سطر

    دعه يشغّل الـ suite والـ type-checker والـ linter، ويعيد تغذية أي لون أحمر، وراجِع الـ diff النهائي بنفسك. أنت المؤلّف المُسجَّل.

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

    ما تحصل عليه loop أخضر وdiff مُراجَع. الـ agent الذي يستطيع *رؤية* اللون الأحمر وإصلاحه يساوي عشرةً لا يقدرون إلا على التفكير في الكود — لكنك تبقى تقرأه، لأنه أحيانًا مخطئ بثقة.

  5. commit في أجزاء نظيفة وصادقة

    اختم بتحويل التغيير إلى تاريخ قابل للمراجعة — commits صغيرة برسائل تشرح *لماذا*، كي يبقى git blame الخاص بك مفيدًا للشخص التالي.

    أنت تطلب 
    ضع هذا في الـ staging كـ commit واحد مركَّز (أو قسّمه إن غطّى أكثر من شأن واحد) وصُغ رسائل commit تشرح لماذا، لا ماذا فقط. أرِني الرسائل قبل الـ commit، ولا تشغّل أي شيء مُدمِّر دون شرحه أولًا.

    ما تحصل عليه commit نظيف (أو تقسيم منطقي) برسالة سيفهمها المُراجِع فعلًا — يبقى تاريخك قابلًا للمراجعة ويبقى git blame لديك صادقًا.

    اطلب منه شرح حالة الـ git *قبل* أي شيء مُدمِّر، ولا تسلّمه أبدًا --force لا تفهمه.

اجعله ملكك

  • **راجِع PR لشخص آخر بدلًا من ذلك:** وجّهه إلى diff وارد — «راجِع هذا كمهندس أوّل متشكّك: الصحّة، وedge cases، والأمان، وأي شيء سيوقظ أحدهم في الثالثة فجرًا. افترض أن هناك bug وحاوِل إيجاده.» الصرامة نفسها، موجَّهةً إلى كود لم تكتبه.
  • **فُكّ working tree فوضوية أولًا:** إن كانت لديك تغييرات غير مُلتزَمة تمتدّ عبر ثلاثة أشياء غير مترابطة وmerge نصف مكتمل، فابدأ بـ «اشرح الحالة الراهنة، ثم ساعِدني في عمل staging وcommit لكل شأن على حدة» — انظَّف قبل أن تبدأ الإصلاح.
  • **plan mode للكبيرة:** إن تبيّن أن الإصلاح إعادة تشكيل حقيقية، فبدّل إلى plan mode ووافِق على المقاربة قبل أي تعديلات — انظر /features/plan-mode/.

انتبه إلى

  • أعطه الأثر الحقيقي — الـ stack trace الكامل، ومخرجات الـ test الفاشل، والخطأ الفعلي — لا إعادة صياغتك. النصّ الحرفي عادةً هو حيث تكمن الإجابة.
  • اطلب الخطة والتشخيص *أولًا*، واقرأهما. أرخص بكثير أن تصحّح مقاربةً خاطئةً في نثرٍ من أن تصحّحها في diff من 300 سطر.
  • اقرأ كل diff قبل أن توافق عليه ولا تتخطَّ الـ test أبدًا. عامل مخرجاته كـ PR من مبتدئ سريع متحمّس — صحيح غالبًا، مخطئ بثقة أحيانًا، ومسؤوليتك أنت للتوقيع عليه دائمًا.

ستحصل في النهاية على في فترة بعد ظهر تنتقل من «لم أرَ هذا الكود قط» إلى إصلاح مُراجَع ومُختبَر تفهمه — إضافةً إلى خريطة ذهنية للـ codebase ستبقى تستخدمها طوال الأسبوع. بقيتَ أنت المهندس؛ وكان Claude القارئ السريع والشريك الذي لا يكلّ.