30 ديسمبر 2025·7 دقيقة
ترياج الأخطاء مع Claude Code: حلقة عملية للإصلاح السريع
ترياج الأخطاء مع Claude Code باستخدام حلقة قابلة للتكرار: استنساخ، تصغير، تحديد الأسباب المحتملة مع أدلة، إضافة اختبار ارتداد، وشحن إصلاح ضيق مع فحوصات تحقق.
ترياج الأخطاء مع Claude Code باستخدام حلقة قابلة للتكرار: استنساخ، تصغير، تحديد الأسباب المحتملة مع أدلة، إضافة اختبار ارتداد، وشحن إصلاح ضيق مع فحوصات تحقق.
الأخطاء تبدو عشوائية عندما يتحول كل تقرير إلى لغز مستقل. تجفف الكود، تجرب بعض الأفكار، وتأمل أن تختفي المشكلة. أحيانًا تختفي، لكنك لا تتعلم كثيرًا، ويظهر نفس الخطأ مرة أخرى بصورة مختلفة.
ترياج الأخطاء هو العكس. إنه طريقة سريعة لتقليل عدم اليقين. الهدف ليس إصلاح كل شيء فورًا. الهدف هو تحويل شك غامض إلى بيان واضح وقابل للاختبار، ثم إجراء أصغر تغيير يثبت أن البيان لم يعد صحيحًا.
لهذا السبب الحلقة مهمة: استنساخ، تصغير، تحديد الأسباب المحتملة مع الأدلة، إضافة اختبار ارتداد، تنفيذ إصلاح ضيق، والتحقق. كل خطوة تزيل نوعًا محددًا من التخمين. إذا تخطيت خطوات ستدفع الثمن لاحقًا بإصلاحات أكبر، آثار جانبية، أو "إصلاحات" لم تُصلح فعليًا.
إليك مثال واقعي. قال مستخدم: "زر الحفظ أحيانًا لا يفعل شيئًا." بدون حلقة قد تتفحّص كود الواجهة وتغيّر التوقيت، الحالة، أو استدعاءات الشبكة. مع الحلقة، تجعل كلمة "أحيانًا" تصبح "دائمًا، تحت هذه الشروط المحددة"، مثل: "بعد تعديل العنوان ثم التنقل سريعًا بين التبويبات، يبقى زر الحفظ معطلاً." جملة واحدة كهذه هي بالفعل تقدم.
يمكن لـ Claude Code تسريع جزء التفكير: تحويل التقارير إلى فرضيات دقيقة، اقتراح أماكن البحث، واقتراح اختبار بسيط يجب أن يفشل. مفيد بشكل خاص في مسح الكود والسجلات والـ diffs الأخيرة لتوليد تفسيرات معقولة بسرعة.
لا يزال عليك التحقق مما يهم. أكّد أن الخطأ حقيقي في بيئتك. فضّل الأدلة (سجلات، تتبعات، اختبارات فاشلة) على قصة تبدو جيدة. اجعل الإصلاح صغيرًا قدر الإمكان، اثبته باختبار ارتداد، وتحقق منه بفحوصات واضحة حتى لا تستبدل خطأ بآخر.
المكسب هو إصلاح صغير وآمن يمكنك شرحه والدفاع عنه ومنع تكراره.
الإصلاحات الجيدة تبدأ بمساحة عمل نظيفة وبيان مشكلة واحد وواضح. قبل أن تسأل Claude، اختر تقريرًا واحدًا وأعد كتابته كالتالي:
"عندما أقوم بـ X، أتوقع Y، لكن أحصل على Z."
إذا لم تستطع كتابة تلك الجملة، فليس لديك خطأ بعد؛ لديك لغز.
اجمع الأساسيات مقدمًا حتى لا تعود للدوران. هذه التفاصيل هي ما يجعل الاقتراحات قابلة للاختبار بدلًا من غامضة: إصدار التطبيق أو الالتزام (ومكانه: محلي، staging، أو إنتاج)، تفاصيل البيئة (نظام التشغيل، المتصفح/الجهاز، أعلام الميزات، المنطقة)، المدخلات الدقيقة (حقول النماذج، حمولة API، إجراءات المستخدم)، من يرى المشكلة (الجميع، دور محدد، حساب/مستأجر واحد)، وماذا يعني "المتوقع" (نسخة النص، حالة الواجهة، كود الحالة، قاعدة العمل).
ثم احفظ الأدلة بينما لا تزال طازجة. طابع زمني واحد يمكن أن يوفر ساعات. التقط السجلات حول الحدث (عميل وخادم إذا أمكن)، لقطة شاشة أو تسجيل قصير، معرفات الطلب أو التتبع، الطوابع الزمنية الدقيقة (مع المنطقة الزمنية)، وأصغر قطعة من البيانات التي تثير المشكلة.
مثال: تطبيق React مولّد بواسطة Koder.ai يعرض "تم الدفع" لكن الطلب يبقى "قيد الانتظار". دوّن دور المستخدم، معرف الطلب بالضبط، جسم استجابة الـ API، وسطور سجل الخادم لذلك معرف الطلب. الآن يمكنك أن تطلب من Claude تركيزه على تدفق واحد بدلًا من التكلم العام.
أخيرًا، حدد قاعدة إيقاف. قرر ما الذي سيُحسب كـمصحح قبل أن تبدأ بالبرمجة: اختبار محدد يمر، حالة واجهة تتغير، خطأ لم يعد يظهر في السجلات، بالإضافة إلى قائمة تحقق قصيرة ستنفذها في كل مرة. هذا يمنعك من "إصلاح" العرض وشحن خطأ جديد.
تقرير الأخطاء الفوضوي عادةً يخلط الحقائق والتخمينات والإحباط. قبل أن تطلب المساعدة، حوّله إلى سؤال واضح يمكن لـ Claude الإجابة عليه بالأدلة.
ابدأ بملخص من جملة واحدة يحدد الميزة والفشل. جيد: "حفظ المسودة أحيانًا يحذف العنوان على الجوال." ليس جيدًا: "المسودات معطلة." تصبح تلك الجملة مرساة لسلسلة الترياج بأكملها.
ثم فصل ما شاهدته عن ما توقعت. اجعلها مملة وملموسة: الزر الذي ضغطته بالضبط، الرسالة على الشاشة، سطر السجل، الطابع الزمني، الجهاز، المتصفح، الفرع، الالتزام. إذا لم تكن تلك التفاصيل متوفرة، فقل ذلك.
هيكل بسيط يمكنك لصقه:
إذا كانت التفاصيل مفقودة، اطلبها كأسئلة نعم/لا حتى يجيب الناس بسرعة: هل يحدث على حساب جديد؟ فقط على الجوال؟ فقط بعد تحديث الصفحة؟ هل بدأ بعد الإصدار الأخير؟ هل يمكن تكراره في وضع التصفح الخفي؟
Claude مفيد أيضًا كـ"منظف للتقارير". الصق التقرير الأصلي (بما في ذلك النص المنسوخ من لقطات الشاشة، السجلات، ومقتطفات الدردشة)، ثم اطلب:
"أعد كتابة هذا كقائمة تحقق منظمة. وعلّم التناقضات. اذكر أهم 5 حقائق مفقودة كأسئلة نعم/لا. لا تخمن الأسباب بعد."
إذا قال زميل "يفشل عشوائيًا"، دفّعه نحو شيء قابل للاختبار: "يفشل 2/10 مرات على iPhone 14، iOS 17.2، عند النقر على حفظ مرتين بسرعة." الآن يمكنك تكراره عن قصد.
إذا لم تستطع جعل الخطأ يحدث عند الطلب، فكل خطوة تالية مجرد تخمين.
ابدأ باستنساخه في أصغر بيئة لا تزال تُظهر المشكلة: بناء dev محلي، فرع مصغر، مجموعة بيانات صغيرة، وأقل عدد ممكن من الخدمات مفعّلة.
اكتب الخطوات بالضبط حتى يتمكن شخص آخر من اتباعها دون أسئلة. اجعلها قابلة للنسخ واللصق: أوامر، معرفات، وحمولات عينة يجب أن تُدرج كما استُخدمت.
قالب قصير للتوثيق:
التكرار يغير استراتيجيتك. الأخطاء "الدائمة" رائعة للتكرار السريع. الأخطاء "الأحيانًا" غالبًا ما تشير إلى توقيت، تخزين مؤقت، ظروف تسابق، أو حالة مخفية.
عند امتلاك ملاحظات الاستنساخ، اطلب من Claude اقتراح اختبارات سريعة تقلل عدم اليقين دون إعادة كتابة التطبيق. الاختبارات الجيدة صغيرة: سطر سجل مستهدف حول الحد الفاشل، علم تصحيح لمكوّن واحد، طريقة لجعل السلوك حتميًا (بذرة عشوائية ثابتة، وقت ثابت، عامل واحد)، مجموعة بيانات صغيرة تحفز المشكلة، أو طلب/استجابة واحدة فاشلة لإعادة التشغيل.
مثال: تدفق التسجيل يفشل "أحيانًا". قد يقترح Claude تسجيل معرف المستخدم المولد، نتيجة تطبيع البريد الإلكتروني، وتفاصيل خطأ قيد التفرد، ثم إعادة تشغيل نفس الحمولة 10 مرات. إذا فشل فقط في التشغيل الأول بعد النشر، فهذه إشارة قوية لفحص الترحيلات، تهيئة الكاش، أو بيانات مفقودة في الإعداد.
استنساخ جيد مفيد. استنساخ مصغر قوي. يجعلك تفهم الخطأ أسرع، يسهل تصحيحه، ويقلل احتمال "الإصلاح بالصدفة".
ازل كل ما ليس ضروريًا. إذا ظهر الخطأ بعد تدفق واجهة طويل، اعثر على أقصر مسار ما زال يثيره. أزل الشاشات الاختيارية، أعلام الميزات، والتكاملات غير المتعلقة حتى يختفي الخطأ (أزلت شيئًا أساسيًا) أو يبقى (وجدت الضوضاء).
ثم قلّص البيانات. إذا احتاج الخطأ حمولة كبيرة، جرّب أصغر حمولة ما زالت تفشل. إذا احتاج إلى قائمة من 500 عنصر، اختبر هل 5 تفشل، ثم 2، ثم 1. أزل الحقول واحدًا تلو الآخر. الهدف هو أقل أجزاء متحركة تظل تُظهر الخطأ.
طريقة عملية: "إزالة النصف ثم إعادة الاختبار":
مثال: صفحة الدفع تتعطل "أحيانًا" عند تطبيق قسيمة. تكتشف أنها تفشل فقط عندما يحتوي السلة على عنصر مخفَّض، القسيمة بأحرف صغيرة، والشحن مضبوط على "استلام". هذه هي حالتك المصغرة: عنصر مخفَّض واحد، قسيمة بحروف صغيرة، خيار استلام واحد.
عند وضوح الحالة المصغرة، اطلب من Claude تحويلها إلى حافظة استنساخ صغيرة: اختبار بسيط يستدعي الدالة المعيبة مع أصغر مدخلات، سكربت قصير يصيب نقطة نهاية بحمولة مصغرة، أو اختبار واجهة صغير يزور مسارًا واحدًا وينفذ إجراءً واحدًا.
بعد أن تستطيع إعادة إنتاج المشكلة ولديك حالة اختبار صغيرة، توقف عن التخمين. هدفك هو الوصول لقائمة قصيرة من الأسباب المحتملة، ثم إثبات أو دحض كل واحد.
قاعدة مفيدة: احتفظ بثلاث فرضيات. أكثر من ذلك عادة يعني أن حالة الاختبار لا تزال كبيرة أو ملاحظاتك غامضة.
حوّل ما تراه إلى أين قد يحدث الخطأ. عرض واجهة لا يعني دائمًا خطأ في الواجهة.
مثال: صفحة React تُظهر رسالة "تم الحفظ" لكن السجل مفقود لاحقًا. قد يشير ذلك إلى (1) حالة الواجهة، (2) سلوك الـ API، أو (3) مسار الكتابة إلى قاعدة البيانات.
اطلب من Claude تفسير أوضاع الفشل المحتملة بلغة بسيطة، ثم اسأل ما الدليل الذي سيؤكد كل واحد. الهدف هو تحويل "ربما" إلى "تحقق من هذا بالضبط".
ثلاث فرضيات شائعة والأدلة التي تجمّعها:
حافظ على ملاحظاتك مركزة: العرض، الفرضية، الدليل، الحكم. عندما تطابق فرضية واحدة الحقائق، يمكنك تثبيت اختبار ارتداد وإصلاح الضروري فقط.
اختبار الارتداد الجيد هو حزام الأمان. يثبت أن الخطأ موجود، ويخبرك متى أصلحتَه فعليًا.
ابدأ باختيار أصغر اختبار يطابق الفشل الحقيقي. إذا ظهر الخطأ فقط عندما تعمل عدة أجزاء معًا، قد يفشل الاختبار الوحدوي في كشفه.
استخدم اختبار وحدة عندما تُعيد دالة واحدة قيمة خاطئة. استخدم اختبار تكاملي عندما تكون المشكلة في الحدّ بين الأجزاء (معالج API + DB، أو الواجهة + الحالة). استخدم نهاية إلى نهاية فقط إذا كان الخطأ يعتمد على التدفق الكامل للمستخدم.
قبل أن تطلب من Claude كتابة أي شيء، أعد صياغة الحالة المصغرة كسلوك متوقع صارم. مثال: "عندما يحفظ المستخدم عنوانًا فارغًا، يجب أن يرجع API كود 400 مع الرسالة 'title required'." الآن لدى الاختبار هدف واضح.
ثم اجعل Claude يصيغ اختبارًا فاشلًا أولًا. اجعل الإعداد بسيطًا ونسخ فقط البيانات التي تحفز الخطأ. سمِّ الاختبار باسم يركز على تجربة المستخدم، وليس الدالة الداخلية.
قم بتمرير سريع بنفسك:
عندما يفشل الاختبار للسبب الصحيح، تكون مستعدًا لتنفيذ إصلاح ضيق بثقة.
عندما تحصل على استنساخ صغير واختبار ارتداد فاشل، قاوم رغبة "تنظيف الأمور". الهدف هو إيقاف الخطأ بأصغر تغيير يجعل الاختبار يمر للسبب الصحيح.
إصلاح ضيق جيد يغيّر أقل مساحة سطح ممكن. إذا كان الخلل في دالة واحدة، أصلح تلك الدالة، لا الوحدة بأكملها. إذا كان يفقد فحص حاجز، أضف الفحص عند الحدّ، لا في كل سلسلة الاستدعاء.
إذا استخدمت Claude للمساعدة، اطلب خيارين للإصلاح ثم قارنهما من حيث النطاق والمخاطر. مثال: إذا تعطل نموذج React عندما يكون الحقل فارغًا:
الخيار أ عادةً اختيار الترياج: أصغر، أسهل للمراجعة، وأقل احتمالًا لكسر شيء آخر.
للحفاظ على ضيق الإصلاح، لمس أقل عدد من الملفات، فضّل الإصلاحات المحلية على إعادة الهيكلة، أضف حراسًا أو تحققًا حيث تدخل القيمة السيئة، واجعل تغيير السلوك صريحًا مع قبل/بعد واضحين. اترك تعليقات فقط عندما لا يكون السبب واضحًا.
مثال ملموس: نقطة نهاية Go تنهار عندما يكون معامل الاستعلام اختياريًا مفقودًا. الإصلاح الضيق هو معالجة السلسلة الفارغة عند حد المعالج (تحليل مع قيمة افتراضية، أو إرجاع 400 برسالة واضحة). تجنّب تغيير أدوات التحليل المشتركة ما لم يثبت اختبار الارتداد أن الخطأ فيها.
بعد التغيير، أعد تشغيل الاختبار الفاشل وواحد أو اثنين من الاختبارات المجاورة. إذا تطلب إصلاحك تحديث العديد من الاختبارات غير المرتبطة، فهذه إشارة أن التغيير واسع جدًا.
التحقق هو المكان الذي تلتقط فيه المشاكل الصغيرة السهلة التغاضي عنها: إصلاح يمر باختبار واحد لكنه يكسر مسارًا قريبًا، يغير رسالة خطأ، أو يضيف استعلامًا بطيئًا.
أعد تشغيل اختبار الارتداد الذي أضفته أولًا. إذا مرّ، شغّل الاختبارات الأقرب: في نفس الملف، نفس الوحدة، وأي شيء يغطي نفس المدخلات. الأخطاء غالبًا تختبئ في Helpers مشتركة، التحليل، الفحوصات الحدية، أو الكاش، لذا تظهر الإخفاقات الأكثر صلة عادةً قريبًا.
ثم قم بفحص يدوي سريع باستخدام خطوات التقرير الأصلية. اجعلها قصيرة ومحددة: نفس البيئة، نفس البيانات، نفس تسلسل النقرات أو استدعاءات الـ API. إذا كان التقرير غامضًا، اختبر السيناريو الدقيق الذي استخدمته لاستنساخه.
إذا رغبت بمساعدة للحفاظ على التركيز، اطلب من Claude خطة تحقق قصيرة بناءً على تغييرك والسيناريو الفاشل. شارك الملف الذي غيرته، السلوك المقصود، وما الذي يمكن أن يتأثر بشكل معقول. أفضل الخطط قصيرة وقابلة للتنفيذ: 5 إلى 8 فحوصات يمكنك إنجازها في دقائق، كل واحدة مع نجاح/فشل واضح.
أخيرًا، سجّل ما تحققته في الـ PR أو الملاحظات: أي اختبارات شغلتها، أي خطوات يدوية جرّبتها، وأي حدود (مثال: "لم يُختبر على الجوال"). هذا يجعل الإصلاح أسهل للثقة والمراجعة لاحقًا.
أسرع طريقة لإضاعة الوقت هي قبول "إصلاح" قبل أن تتمكن من استنساخ المشكلة عند الطلب. إذا لم تستطع جعله يفشل باستمرار، فلن تعرف ما الذي تحسّن فعليًا.
قاعدة عملية: لا تطلب إصلاحات حتى تستطيع وصف إعداد قابل للتكرار (خطوات دقيقة، مدخلات، بيئة، وما يبدو "خاطئًا"). إذا كان التقرير غامضًا، اقضِ أول دقائقك في تحويله إلى قائمة تحقق يمكنك تنفيذها مرتين والحصول على نفس النتيجة.
الإصلاح بدون حالة استنساخ قابلة للتكرار. اشترط سكربت بسيط "يفشل في كل مرة" أو مجموعة خطوات. إذا كان فقط "أحيانًا"، التقط التوقيت، حجم البيانات، أعلام الميزات، والسجلات حتى يتوقف عن العشوائية.
التصغير مبكرًا جدًا. إن قلّصت الحالة قبل تأكيد الفشل الأصلي يمكنك فقدان الإشارة. أولًا ثبت استنساخ الأساس، ثم قلّص خطوة بخطوة.
ترك Claude يخمن. يمكن لـ Claude اقتراح الأسباب المحتملة، لكنك ما تزال بحاجة لأدلة. اطلب 2 إلى 3 فرضيات والمرصوفات الدقيقة التي تؤكد أو تنفي كل واحدة (سطر سجل، نقطة توقف، نتيجة استعلام).
اختبارات ارتداد تمر للسبب الخاطئ. قد يمر اختبار لأن المسار الفاشل لم يُستهدف أبدًا. تأكد أنه يفشل قبل الإصلاح وأنه يفشل بالرسالة أو Assertion المتوقعة.
معالجة الأعراض بدلًا من المسبب. إذا أضفت فحص null لكن المشكلة الحقيقية أن "هذه القيمة لا يجب أن تكون null أبدًا" فقد تُخفي خطأ أعمق. فضّل إصلاح الشرط الذي يخلق الحالة السيئة.
شغّل اختبار الارتداد الجديد وخطوات الاستنساخ الأصلية قبل وبعد التغيير. إذا كان خطأ الدفع يحدث فقط عند تطبيق كود ترويجي بعد تغيير الشحن، احتفظ بذلك التسلسل الكامل كـ"حقيقتك"، حتى لو كان اختبارك المصغر أصغر.
إذا كان تحقّقك يعتمد على "يبدو جيدًا الآن"، أضف فحصًا ملموسًا (سطر سجل، مقياس، أو مخرج محدد) حتى يتمكن الشخص التالي من التحقق بسرعة.
عندما تكون تحت ضغط الوقت، حلقة صغيرة قابلة للتكرار تفوق التصحيحات البطولية.
اكتب القرار النهائي في بضعة أسطر حتى يثق به الشخص التالي (غالبًا أنت في المستقبل). صيغة مفيدة: "السبب الجذري: X. الزناد: Y. الإصلاح: Z. لماذا آمن: W. ما لم نغيره: Q."
الخطوات التالية: أتمتة ما يمكنك (سكربت استنساخ محفوظ، أمر اختبار قياسي، قالب لملاحظات السبب الجذري).
إذا بنت تطبيقات باستخدام Koder.ai (koder.ai)، يمكن أن يساعدك وضع التخطيط Planning Mode في وضع مخطط للتغيير قبل أن تلمس الكود، واللقطات/الاسترجاع تسهّل التجربة الآمنة أثناء عملك على استنساخ معقد. بعد التحقق من الإصلاح يمكنك تصدير الشيفرة المصدرية أو نشر التطبيق المحدث، بما في ذلك على نطاق مخصص عند الحاجة.
Bug triage هو عادة تحويل تقرير غامض إلى بيان واضح وقابل للاختبار، ثم إجراء أصغر تغيير يثبت أن هذا البيان لم يعد صحيحًا.
الأمر يتعلق أقل بـ"إصلاح كل شيء" وأكثر بتقليل عدم اليقين خطوة بخطوة: استنساخ، تصغير، وضع فرضيات مدعومة بأدلة، إضافة اختبار ارتداد، إصلاح ضيق، والتحقق.
لأن كل خطوة تزيل نوعًا مختلفًا من التخمين.
أعد صياغتها كالتالي: “عند قيامي بـ X أتوقع Y، لكن أحصل على Z.”
ثم اجمع فقط السياق الكافي لجعلها قابلة للاختبار:
ابدأ بالتأكد أنك تستطيع إعادة إنتاجه في أصغر بيئة لا تزال تظهر المشكلة (غالبًا بيئة dev محلية مع مجموعة بيانات صغيرة).
إذا كان "أحيانًا"، حاول جعله حتميًا عبر التحكم بالمتغيرات:
لا تتقدم حتى تتمكن من جعله يفشل عند الطلب، وإلا فأنت تخمّن.
التصغير يعني إزالة أي شيء غير ضروري مع الحفاظ على ظهور الخطأ.
طريقة عملية: “اقطع العناصر إلى النصف ثم أعد الاختبار”:
قلص كل من الخطوات (تدفق المستخدم) والبيانات (حمولة أصغر، حقول/عناصر أقل) حتى تحصل على أصغر مُحَرّك يمكن تكراره.
استخدم Claude Code لتسريع التحليل، لا لاستبدال التحقق.
طلبات جيدة تبدو مثل:
ثم تحقق بنفسك: أعد الإنتاج محليًا، وافحص السجلات/التتبعات، وتأكد أن أي اختبار يفشل للسبب الصحيح.
حافظ على ثلاث فرضيات كحد أقصى. أكثر من ذلك عادةً يعني أن حالة الاستنساخ لا تزال كبيرة أو ملاحظاتك غامضة.
لكل فرضية اكتب:
هذا يجبر التقدم ويمنع اختبار التخمين اللا نهائي.
اختر أصغر مستوى اختبار يطابق الفشل:
اختبار ارتداد جيد:
قم بأصغر تغيير يجعل اختبار الارتداد يفشل ثم يمر للسبب الصحيح.
قواعد بسيطة:
استخدم قائمة تحقق قصيرة يمكنك تنفيذها بسرعة:
سجل ما نفذته وما لم تختبره حتى يكون القرار موثوقًا.