ما الذي أحتاج تجهيزه قبل البدء — هل يكفي تقرير الـ bug وحده؟

تحتاج أربعة أشياء: المجلد الجذر للمشروع مفتوحًا في Claude Desktop (لا مجلد أعلى منه)، والـ stack trace كاملًا حرفيًا (لا إعادة صياغة)، وطريقة لإعادة إنتاج الـ bug، وworking tree نظيف مع توافر أوامر الـ test suite والـ type-checker والـ linter. رسم الخريطة والتشخيص والإصلاح تجري بالكامل في Claude Desktop؛ أما تشغيل الـ loop والـ commit فهما خطوتا مسار Power Track اللتان تحتاجان جلسة مفعّلة للـ Terminal. الـ trace الحرفي هو المدخل الأهم؛ «ينهار عند تسجيل الدخول» يرمي بعيدًا الـ frame المحدّد الذي يحمل الإجابة.

كم يستغرق القوس الكامل في الأسبوع الأول؟

ضع في حسبانك نصف يوم تقريبًا للـ workflow كاملًا — نحو 15 دقيقة لرسم الخريطة، و15-20 دقيقة للتشخيص والتأكيد، و20-30 دقيقة للإصلاح والـ test، ووقت للـ loop النهائي والـ commit. خطوة رسم الخريطة هي التي يتخطّاها الناس أكثر ما يتخطّون، وهي التي توفّر أكبر قدر من وقت الـ debug.

لماذا يُصرّ الـ playbook على «لا تُصلح أي شيء بعد» أثناء التشخيص؟

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

ماذا لو تبيّن أن الإصلاح إعادة تشكيل أكبر بكثير مما توقّعت؟

بدّل إلى plan mode قبل أي تعديلات. اطلب من Claude الخطة الكاملة ووافِق عليها صراحةً — انظر خيار الـ plan-mode في هذا الـ playbook. bug صغير يكشف مشكلة بنيوية هو بالضبط السيناريو الذي صُمّم plan mode من أجله؛ لا تدعه يبدأ إعادة الكتابة بلا موافقتك.

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

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

وظيفة جديدة، الأسبوع الأول. هناك bug في الـ production، ومن كتب الـ auth flow غادر قبل شهرين، والـ README متأخّر بثلاث إعادات كتابة. عادةً هذا يومٌ من الـ grep، ويومٌ من التخمين، وcommit لست واثقًا منه. هذا النظام يمشي القوس كاملًا — اقرأ الـ repo، شخّص من الأدلّة، أصلِح بـ test يُثبت الإصلاح، وcommit بنظافة — كي تبقى أنت المهندس ويكون Claude القارئ السريع والشريك الذي لا يكلّ. هذا هو المشروع الختامي للمسار المُرحَّل: يربط كل playbook هندسي سابق في حركة واحدة — الخريطة (الـ map-the-codebase)، وسياق المشروع (الـ project-context)، والتشخيص المبني على الأدلّة (الـ debug-from-trace)، والـ test الذي يُثبت الإصلاح (الـ backfill-tests)، والتنظيف الحافظ للسلوك (الـ safe-refactor)، والـ commit الصغير الصادق (الـ git-workflow). القراءة والتشخيص والإصلاح تعيش بالكامل في Claude Desktop كمحادثة إضافةً إلى ديفات مرئية تقبلها أو ترفضها؛ أما تشغيل الـ loop الحقيقي والـ commit فهما خطوتا مسار Power Track (جلسة مفعّلة للـ Terminal).

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

المجلد الجذر للمشروع مفتوحًا في Claude Desktop، كي يقرأ Claude ملفاتك الفعلية — لا ذاكرته عن شكل الـ repos المشابهة عادةً. (مسار Power Track: تشغيل claude في المجلد الجذر من الـ Terminal يفعل الشيء نفسه.)
تقرير الـ bug، وإن وُجد، الـ stack trace الكامل مع طريقة لإعادة إنتاجه — الصقه مباشرةً في المحادثة.
working tree نظيفة، وأوامر الـ test suite والـ type-checker والـ linter — كي يستطيع Claude (في جلسة مفعّلة للـ Terminal) تشغيل الـ loop الحقيقي لديك ورؤية اللون الأحمر، أو كي تشغّله أنت بنفسك وتلصق الناتج.

الـ workflow

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

افتح المجلد في Claude Desktop واسأل في المحادثة — رسم خريطة repo لا يحتاج Terminal. لا تنقضّ على الـ bug مباشرةً دون تحضير: خصّص عشر دقائق لأخذ صورة عامة، كي تُصحِّح بنموذج ذهني للنظام، لا بمصباح يدوي في الظلام.

أنت تطلب

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

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

إن وصف نسخة عامة من الـ framework الخاص بك بدل ملفاتك الفعلية، فهو لم يقرأ الـ repo. تأكّد أن المجلد الجذر للمشروع هو المفتوح في Claude Desktop (أو أنك شغّلت claude من المجلد الجذر).
شخّص الـ bug من الأدلّة، مُرتَّبًا

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

أنت تطلب

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

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

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

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

أنت تطلب

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

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

دعه يشغّل الـ suite والـ type-checker والـ linter، وأعِد إليه أي نتيجة حمراء، وراجِع الـ diff النهائي بنفسك. تشغيل الـ loop الخاص بمشروعك يحتاج جلسة مفعّلة للـ Terminal (Claude Code في الـ Terminal، أو Claude Desktop مع تفعيل تشغيل الأوامر) — هذه خطوة مسار Power Track. لا جلسة Terminal؟ شغّل الـ loop بنفسك والصق أي أحمر في محادثة Claude Desktop؛ يُصلح Claude من الناتج الحقيقي بالطريقة نفسها. أنت المؤلّف المُسجَّل.

أنت تطلب

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

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

اختم بتحويل التغيير إلى تاريخ قابل للمراجعة — commits صغيرة برسائل تشرح لماذا، كي يبقى git blame الخاص بك مفيدًا للشخص التالي. قيادة git خطوة في مسار Power Track تحتاج جلسة مفعّلة للـ Terminal؛ إن كنت باقيًا على Claude Desktop، فاقبل الديفات هناك ونفّذ الـ commits بنفسك بالرسائل التي يصوغها Claude.

أنت تطلب

ضع هذا في الـ 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 من مبتدئ سريع متحمّس — صحيح غالبًا، مخطئ بثقة أحيانًا، ومسؤوليتك أنت للتوقيع عليه دائمًا. أنت المؤلّف المُسجَّل على كل سطر ينزل.
أبقِ الكود المملوك والأسرار وبيانات العملاء داخل الحدّ. افتح Claude في الـ repo الفعلي كي يقرأ ملفاتك الحقيقية، لكن على Claude Desktop المجلد المفتوح هو الحدّ — وافِق على كل قراءة في نافذة Ask permissions، وأبقِ بيانات الاعتماد وأي شيء تحت NDA خارج الـ context.

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

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

ما الذي أحتاج تجهيزه قبل البدء — هل يكفي تقرير الـ bug وحده؟: تحتاج أربعة أشياء: المجلد الجذر للمشروع مفتوحًا في Claude Desktop (لا مجلد أعلى منه)، والـ stack trace كاملًا حرفيًا (لا إعادة صياغة)، وطريقة لإعادة إنتاج الـ bug، وworking tree نظيف مع توافر أوامر الـ test suite والـ type-checker والـ linter. رسم الخريطة والتشخيص والإصلاح تجري بالكامل في Claude Desktop؛ أما تشغيل الـ loop والـ commit فهما خطوتا مسار `Power Track` اللتان تحتاجان جلسة مفعّلة للـ Terminal. الـ trace الحرفي هو المدخل الأهم؛ «ينهار عند تسجيل الدخول» يرمي بعيدًا الـ frame المحدّد الذي يحمل الإجابة.
كم يستغرق القوس الكامل في الأسبوع الأول؟: ضع في حسبانك نصف يوم تقريبًا للـ workflow كاملًا — نحو 15 دقيقة لرسم الخريطة، و15-20 دقيقة للتشخيص والتأكيد، و20-30 دقيقة للإصلاح والـ test، ووقت للـ loop النهائي والـ commit. خطوة رسم الخريطة هي التي يتخطّاها الناس أكثر ما يتخطّون، وهي التي توفّر أكبر قدر من وقت الـ debug.
لماذا يُصرّ الـ playbook على «لا تُصلح أي شيء بعد» أثناء التشخيص؟: لأن التشخيص هو الخطوة الأكثر احتمالًا للخطأ، وأرخص بكثير أن تكتشف فرضية خاطئة في نثر قبل تحويلها إلى diff من 300 سطر. قراءة قائمة الأسباب المرتّبة وتأكيد الصحيح منها قبل أي تغيير في الكود هو ما يمنعك من قضاء ساعة على الإصلاح الخاطئ.
ماذا لو تبيّن أن الإصلاح إعادة تشكيل أكبر بكثير مما توقّعت؟: بدّل إلى plan mode قبل أي تعديلات. اطلب من Claude الخطة الكاملة ووافِق عليها صراحةً — انظر خيار الـ `plan-mode` في هذا الـ playbook. bug صغير يكشف مشكلة بنيوية هو بالضبط السيناريو الذي صُمّم plan mode من أجله؛ لا تدعه يبدأ إعادة الكتابة بلا موافقتك.