كيف تكتب تقرير خطأ جيدًا (للذكاء الاصطناعي أو للمطوّر)

تقرير الخطأ الجيد يتيح لشخص آخر، سواء كان مطوّرًا أو ذكاءً اصطناعيًا، أن يرى المشكلة نفسها التي رأيتها، دون أن يضطر إلى طرح أي سؤال عليك. يحتاج إلى عنوان محدد، وخطوات دقيقة لإعادة إنتاجها، وما كنت تتوقعه، وما حدث فعلًا، ونص أي رسالة خطأ منسوخ حرفيًا، وأين حدثت: أي صفحة، وأي متصفح، وأي جهاز، وأي مستخدم. خطأ واحد في كل تقرير، مع لقطة شاشة إن كانت مفيدة.

معظم الأخطاء تستغرق لفهمها وقتًا أطول مما يستغرقه إصلاحها. التقرير الواضح يزيل جزء الفهم. وهذا أهم مع أدوات الذكاء الاصطناعي: فالذكاء الاصطناعي لا يستطيع أن يطرح سؤالًا متابعًا عما تعنيه بقولك «الدفع غريب»، فيخمّن، والتخمين الخاطئ قد يكسر شيئًا آخر.

القالب

انسخ هذا واملأه:

العنوان: [ما الخطأ، وأين] — مثال: "نموذج الحجز يرفض الأوقات بعد السادسة مساءً"

خطوات إعادة الإنتاج:
1. ...
2. ...
3. ...

المتوقع: [ما الذي يجب أن يحدث]
الفعلي: [ما الذي حدث بدلًا من ذلك]

رسالة الخطأ: [النص الحرفي، إن وُجد]
أين: [الصفحة/الرابط، والمتصفح، والجهاز، وتسجيل الدخول باسم أي مستخدم]
عدد مرات الحدوث: [في كل مرة / أحيانًا / مرة واحدة]
لقطة شاشة أو تسجيل: [مرفق]

يشرح بقية هذا الدليل كل جزء.

الخطوة 1: أعد إنتاج الخطأ أولًا

قبل الكتابة، حاول أن تجعل الخطأ يحدث مرة أخرى. ستعرف الخطوات التي تهم، وهل يحدث في كل مرة.

• ابدأ من حالة نظيفة: حدّث الصفحة، أو سجّل الخروج ثم الدخول.
• دوّن كل نقرة وكل شيء تكتبه.
• حاول أن تجد أقصر مسار يُفعّل الخطأ.
• جرّب متصفحًا ثانيًا أو حسابًا آخر. إذا حدث الخطأ لمستخدم واحد فقط، فهذا دليل مهم.

لمزيد من التفاصيل حول ذلك، راجع كيف تُصحّح تطبيقًا مبنيًا بالذكاء الاصطناعي.

الخطوة 2: اكتب عنوانًا محددًا

يجب أن يقول العنوان ما المشكلة وأين، حتى يعرف من يتصفح قائمة من يقرأ أي خطأ هو.

الخطوة 3: اذكر الخطوات بدقة

رقّمها. كن حرفيًا: أي صفحة، وأي زر، وماذا كتبت.

1. سجّل الدخول كعميل (حساب تجريبي: customer@example.com).
2. أضف «Starter kit» إلى السلة.
3. أدخل رمز الخصم WELCOME10 واضغط Apply.
4. اضغط Checkout.

قول «جرّب الدفع برمز» يُغفل التفاصيل التي كثيرًا ما تكون مهمة: أي مستخدم، وأي منتج، وأي رمز، وهل طُبّق الرمز أولًا.

الخطوة 4: المتوقع مقابل الفعلي

هذا هو قلب التقرير. اذكر الاثنين، لأن الفرق بينهما هو الخطأ.

• المتوقع: تفتح صفحة الدفع مع عرض خصم 10% في الإجمالي.
• الفعلي: يظهر الزر دوّارًا لثانية، ثم لا يحدث شيء. بدون رمز الخصم يعمل الدفع.

بدون «المتوقع»، قد لا يعرف القارئ أن السلوك خاطئ. وبدون «الفعلي»، لا يعرف ما الذي يبحث عنه.

الخطوة 5: انسخ الأخطاء بدقة

رسائل الخطأ هي أسرع طريق إلى السبب. انسخها كنص، حرفيًا، ولا تعِد صياغتها.

أين تجدها:

• على الشاشة: أي رسالة يعرضها التطبيق.
• وحدة تحكم المتصفح (Console): افتح أدوات المطور (F12، أو انقر بالزر الأيمن ← Inspect) وانظر إلى تبويب Console للبحث عن أسطر حمراء.
• تبويب الشبكة (Network): في أدوات المطور، جِد الطلب الفاشل ودوّن عنوانه ورمز حالته (مثلًا POST /api/checkout → 500).
• سجلات الخادم، إذا كان لديك وصول إليها.

سطر مثل TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 يشير غالبًا مباشرة إلى المشكلة.

الخطوة 6: أضف السياق

• أين: رابط الصفحة، والبيئة (معاينة، أو تجربة، أو إنتاج).
• من: أي مستخدم أو دور، مثل مسؤول، أو عضو، أو غير مسجّل الدخول.
• الجهاز والمتصفح: «Safari على iPhone» مقابل «Chrome على Windows» قد يكون مهمًا.
• البيانات: أي شيء غير معتاد في السجل، كنص طويل جدًا، أو أحرف خاصة، أو عدد كبير من العناصر.
• متى بدأ: «بعد تغيير أمس في رموز الخصم» معلومة ذهبية.
• عدد مرات الحدوث: في كل مرة، أو مرة من بين عشر محاولات.

الخطوة 7: أرِ المشكلة

لقطة شاشة تُظهر المشكلة مؤطّرة، أو تسجيل شاشة قصير، يزيل الغموض، خاصة في أخطاء التخطيط. إذا كانت أداتك تقبل الصور، فأرفق واحدة. واقتطع أي شيء خاص، بما في ذلك المفاتيح وبيانات الآخرين.

كتابة تقارير الأخطاء لأداة البناء بالذكاء الاصطناعي

البنية نفسها تصلح كطلب. وتضيف إضافتان فارقًا:

• قل ما يجب ألا يتغير، حتى لا يسبب الإصلاح مشكلة جديدة.
• اطلب منه التحقق من الإصلاح، لا كتابته فقط.

مسجّل الدخول كعميل، و«Starter kit» في السلة، ورمز WELCOME10 مطبّق، وعند الضغط على Checkout لا يحدث شيء. المتوقع: تفتح صفحة الدفع مع خصم 10% من الإجمالي. الفعلي: دوّار لثانية ثم لا شيء. تُظهر تبويب الشبكة أن POST /api/checkout أعاد 500. الدفع بدون رمز يعمل. ابحث عن السبب وأصلحه دون تغيير طريقة حساب الأسعار للطلبات التي بلا رمز. ثم تحقّق من الدفع برمز نسبة مئوية، وبرمز مبلغ ثابت، وبدون رمز.

إذا لم تكن متأكدًا من السبب، فاطلب التشخيص أولًا:

لا تغيّر الكود بعد. بناءً على هذا التقرير، ما الأسباب المحتملة، وما الذي سيؤكد كلًا منها؟

أخطاء شائعة

• «إنه معطّل». لا خطوات، ولا نتيجة متوقعة، ولا شيء يمكن التصرف بناءً عليه.
• عدة أخطاء في تقرير واحد. بعضها يُصلح، والبعض الآخر يضيع.
• أخطاء مُعاد صياغتها. «شيء ما غير معرّف» يخفي الجزء المفيد.
• إغفال المستخدم أو الدور. كثير من الأخطاء تؤثر فقط على المسؤولين، أو فقط على المستخدمين الجدد.
• وصف الإصلاح الذي تريده فقط («أضف فحص null») بدلًا من وصف المشكلة.
• مشاركة أسرار في لقطات الشاشة أو السجلات الملصوقة.

قائمة التحقق

• أعدت إنتاج الخطأ ووجدت أقصر خطوات.
• يقول العنوان ما المشكلة وأين.
• الخطوات مرقّمة وحرفية.
• ذكرت المتوقع والفعلي معًا.
• نسخت رسائل الخطأ حرفيًا، مع أي طلب فاشل ورمز حالته.
• ذكرت الصفحة والبيئة والمستخدم والجهاز والمتصفح.
• ذكرت عدد مرات الحدوث ومتى بدأ.
• أرفقت لقطة شاشة أو تسجيلًا، وأزلت البيانات الخاصة.
• تقرير واحد لخطأ واحد.

الإبلاغ عن الأخطاء لوكيل Mythex

في مشروع Mythex، يكون التقرير هو الطلب. بعض الميزات تساعد:

• أرفق لقطة شاشة للمعاينة أو لشاشة الخطأ، حتى 5 ملفات في الرسالة الواحدة.
• الأمر /fix يوجّه الوكيل إلى إصلاح خطأ، ووضع Plan يتيح له التحقيق قبل التعديل.
• الأمر /test يجعل الوكيل يعيد إنتاج التدفقات في المعاينة نفسها ويبلغ عما يراه.
• Revert to this point يتراجع عن إصلاح زاد الأمور سوءًا.

تستخدم صفحة تصحيح الأخطاء بالطلبات في الوثائق الخطوات نفسها: الخطوات، والمتوقع، والفعلي. أما حلقة الإصلاح والتحقق المحيطة بذلك فراجع كيف تُكرر التحسين على تطبيق بُني بالذكاء الاصطناعي.

الأسئلة