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

playbook

تتبّع bug حتى root cause وأثبت أن الإصلاح صحيح

سلّم Claude الـ stack trace كاملًا والـ input الذي يُفشِل العملية، فتحصل على قائمة مرتّبة بالأسباب المرجّحة مع مؤشّرات `file:line`، ثم إصلاحًا مع test يفشل على الكود القديم وينجح على الجديد.

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

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

يبلّغ المستخدمون أنهم يُسجَّل خروجهم عشوائيًا. لديك stack trace، وrequest يُطلِق المشكلة، ودزينة مشتبهين معقولين. الفخّ هو أن تبدأ بترقيع أول شيء يبدو خاطئًا. هذا النظام يجعلك تُصحّح من *الدليل* — التشخيص أولًا، مرتّبًا حسب الترجيح، ثم إصلاحًا تستطيع إثباته بـ test بدل «هذا يُفترض أن يحلّها» المفعمة بالأمل.

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

  • الـ stack trace **كاملًا**، حرفيًا — كل frame، لا «ينهار عند تسجيل الدخول». الـ frames المحدّدة هي عادةً حيث تكمن الإجابة.
  • الـ request أو الـ input أو الخطوات التي تُعيد إنتاج المشكلة — كلما كانت أصغر وأدقّ كان أفضل.
  • الـ repo مفتوحًا في المجلد الجذر للمشروع، حتى يقرأ Claude الملفات الفعلية التي يشير إليها الـ trace.

الـ workflow

  1. شخّص قبل أن ترقّع — ورتّب الأسباب

    افرض قائمة فرضيات قبل أي تغيير في الكود. تريد التحقّق من سلامة المنطق وهو ما زال نصًّا رخيصًا، لا بعد أن يصير diff من 200 سطر.

    أنت تطلب 
    هذا الـ stack trace كاملًا والـ request الذي أطلقه. تتبّع المنطق من بدايته إلى نهايته وأعطني الأسباب الثلاثة الأرجح لـ root cause، مرتّبةً، مع الملف والسطر لكلٍّ منها والتعليل. لا تُصلح شيئًا بعد.

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

    «لا تُصلح شيئًا بعد» تؤدّي عملًا حقيقيًا هنا. التشخيص هو الجزء الذي تحتاج أكثر ما تحتاج إلى فحصه بحُكمك أنت.

  2. أكّد السبب الحقيقي مقابل الكود

    اختر الفرضية المناسبة واجعل Claude يثبت أنها هي — بالإشارة إلى مسار الكود الدقيق، لا بالجزم بها.

    أنت تطلب 
    السبب رقم 2 يبدو صحيحًا. أرِني مسار الكود الدقيق الذي يُنتج هذا الـ bug — الأسطر التي تضبط الحالة الخاطئة والأسطر التي تقرؤها — واشرح لماذا السلوك الحالي خاطئ.

    ما تحصل عليه مسارٌ ملموس من السبب إلى العَرَض عبر الملفات الفعلية، حتى تفهم الـ bug، لا مجرّد الترقيع الذي توشك أن توافق عليه.

  3. أصلِحه، واكتب الـ test الفاشل أولًا

    أي تغيير بلا test حوّله إلى أخضر هو تخمين. اطلب الـ regression test الذي يُعيد إنتاج الـ bug، ثم أصغر إصلاح يقلبه.

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

    ما تحصل عليه regression test ينتقل من فاشل إلى ناجح مع diff محكم. الـ test الذي يتحوّل من أحمر إلى أخضر هو الإيصال على أن الإصلاح يعالج *الـ bug* نفسه، لا مجرّد العَرَض الذي وصفته.

  4. شغّل الـ loop الحقيقي واقرأ الـ diff

    دعه يشغّل الـ suite والـ type-checker الفعليّين لديك، وأعِد إليه أي أحمر، واقرأ كل سطر قبل أن توافق. ما زلت أنت المؤلّف المسؤول.

    أنت تطلب 
    شغّل الـ test suite كاملًا والـ type-checker. إن كان أي شيء أحمر، أصلِحه وأرِني ما تغيّر. ثم أعطني الـ diff النهائي لأراجعه.

    ما تحصل عليه suite خضراء وdiff مُراجَع — صحيح غالبًا، خاطئ بثقة أحيانًا، وهذا تحديدًا سبب قراءتك له.

اجعله ملكك

  • **لا إعادة إنتاج بعد:** ابدأ بـ «اكتب أصغر script أو test يُعيد إنتاج هذا من الـ trace» — بمجرّد أن يُعيد الإنتاج، ينطبق بقية النظام.
  • **Heisenbug:** اطلب منه أن يضيف logging موجّهًا حول المشتبهين المرتّبين، يشغّل من جديد، ويستدلّ من الناتج الجديد بدل التخمين في العتمة.

انتبه إلى

  • الصق الـ trace والـ input **حرفيًا** — لا تُلخّص. «ينهار عند تسجيل الدخول» يرمي بعيدًا الـ frame المحدّد الذي يحمل الإجابة.
  • اجعله يثبت الإصلاح بـ test ينتقل من فاشل إلى ناجح. شرحٌ واثق بلا test أحمر حوّله إلى أخضر يبقى تخمينًا.
  • اقرأ الـ diff قبل أن توافق عليه. عامل ناتجه كأنه PR من junior سريع ومتحمّس — صحيح غالبًا، خاطئ بثقة تامّة أحيانًا.

ستحصل في النهاية على تنتقل من bug يبدو عشوائيًا إلى root cause تفهمه وإصلاحٍ مدعوم بـ regression test — مُصحَّح من الدليل في فترة بعد ظهر، لا مُخمَّن خلال يومين.