ما الذي أحتاج تجهيزه قبل البدء؟

الـ stack trace كاملًا حرفيًا (كل frame — لا تُلخّصه أبدًا)، والـ request أو الـ input الدقيق الذي يُعيد إنتاج الـ bug، والمجلد الجذر للمشروع مفتوحًا في Claude Desktop كي يقرأ الملفات الفعلية التي يشير إليها الـ trace. التشخيص والإصلاح يجريان بالكامل في Claude Desktop — وحده تشغيل الـ test suite الخاص بمشروعك خطوة في مسار Power Track تحتاج جلسة مفعّلة للـ Terminal. الـ trace الحرفي هو المدخل الأهم؛ الـ frames المحدّدة هي عادةً حيث يختبئ الـ root cause.

لماذا نطلب قائمة أسباب مرتّبة بدل طلب الإصلاح مباشرةً؟

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

كيف أتأكّد أن الإصلاح حقيقي وليس مجرد تحايل على العَرَض؟

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

ماذا لو لم أستطع إعادة إنتاج الـ bug للحصول على trace نظيف؟

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

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

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

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

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

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

الـ workflow

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

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

أنت تطلب

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

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

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

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

أنت تطلب

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

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

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

أنت تطلب

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

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

دعه يشغّل الـ suite والـ type-checker الفعليّين لديك، وأعِد إليه أي أحمر، واقرأ كل سطر قبل أن توافق. تشغيل الـ test command الخاص بمشروعك خطوة في مسار Power Track — يحتاج جلسة مفعّلة للـ Terminal (Claude Code في الـ Terminal، أو Claude Desktop مع تفعيل تشغيل الأوامر). ما زلت أنت المؤلّف المسؤول.

أنت تطلب

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

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

لا جلسة Terminal في متناولك؟ شغّل الـ suite بنفسك كما تفعل عادةً، والصق أي إخفاقات في محادثة Claude Desktop، ودع Claude يستدلّ من الناتج الحقيقي — الـ loop نفسه، لكنك أنت من يضغط Enter.

اجعله ملكك

لا إعادة إنتاج بعد: ابدأ بـ «اكتب أصغر script أو test يُعيد إنتاج هذا من الـ trace» — بمجرّد أن يُعيد الإنتاج، ينطبق بقية النظام.
Heisenbug: اطلب منه أن يضيف logging موجّهًا حول المشتبهين المرتّبين، يشغّل من جديد، ويستدلّ من الناتج الجديد بدل التخمين في العتمة.
اجعل الإصلاح بداية شبكة أمان: الـ test الذي كتبته هنا وانتقل من فاشل إلى ناجح هو أول حالة في suite حقيقي — حين يكون الـ module المحيط بالـ bug ضعيف التغطية بالـ tests، سلّمه مباشرةً إلى playbook الـ backfill-tests كي لا يكون التغيير التالي في ذلك الملف مقامرةً جديدة. وإن كان الـ bug يعيش في ركن من repo لا تعرفه، وجّه Claude أولًا إلى الـ CLAUDE.md الذي بنيته في project-context، واستعِن بـ subagent في بحثٍ واسع عبر ملفات كثيرة كي لا يزاحم التنقيب العميق سياقك الرئيسي (انظر ميزة الـ subagents).

انتبه إلى

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

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

أسئلة يطرحها الناس

ما الذي أحتاج تجهيزه قبل البدء؟: الـ stack trace كاملًا حرفيًا (كل frame — لا تُلخّصه أبدًا)، والـ request أو الـ input الدقيق الذي يُعيد إنتاج الـ bug، والمجلد الجذر للمشروع مفتوحًا في Claude Desktop كي يقرأ الملفات الفعلية التي يشير إليها الـ trace. التشخيص والإصلاح يجريان بالكامل في Claude Desktop — وحده تشغيل الـ test suite الخاص بمشروعك خطوة في مسار `Power Track` تحتاج جلسة مفعّلة للـ Terminal. الـ trace الحرفي هو المدخل الأهم؛ الـ frames المحدّدة هي عادةً حيث يختبئ الـ root cause.
لماذا نطلب قائمة أسباب مرتّبة بدل طلب الإصلاح مباشرةً؟: لأن الإصلاح المعقول الأول كثيرًا ما يكون الخاطئ. إجبار Claude على إنتاج قائمة فرضيات مرتّبة قبل أي تغيير في الكود يعني فحص المنطق وهو ما زال نصًّا رخيصًا — لا بعد أن ينتج diff من 200 سطر في الاتجاه الخاطئ. اقرأ القائمة وأكّد السبب الصحيح، ثم اطلب الإصلاح.
كيف أتأكّد أن الإصلاح حقيقي وليس مجرد تحايل على العَرَض؟: اطلب regression test يفشل على الكود الحالي وينجح بعد الإصلاح، وذلك قبل كتابة الإصلاح نفسه. الـ test الذي ينتقل من أحمر إلى أخضر هو الإيصال على أن التغيير يعالج الـ root cause لا مجرّد العَرَض. شرح واثق بلا test ينتقل من فاشل إلى ناجح يبقى تخمينًا.
ماذا لو لم أستطع إعادة إنتاج الـ bug للحصول على trace نظيف؟: ابدأ بـ «اكتب أصغر script أو test يُعيد إنتاج هذا من الـ trace» — بمجرد أن يُعيد الإنتاج بشكل موثوق، ينطبق بقية هذا الـ playbook. لـ Heisenbug لا يظهر إلا تحت حمل أو توقيت معيّن، اطلب من Claude إضافة logging موجّه حول المشتبهين المرتّبين، يشغّل مجددًا، ويستدلّ من الناتج الجديد بدل التخمين في العتمة.