نحوه نوشتن یک گزارش خطای خوب (برای هوش مصنوعی یا توسعه‌دهنده)

یک گزارش خطای خوب به شخص دیگری — یک توسعه‌دهنده یا یک هوش مصنوعی — اجازه می‌دهد همان مشکلی را ببیند که شما دیدید، بدون اینکه چیزی از شما بپرسد. به یک عنوان مشخص، مراحل دقیق برای بازتولید آن، آنچه انتظار داشتید، آنچه واقعاً رخ داد، هر پیام خطا که عیناً کپی شده، و محل وقوع آن نیاز دارد: کدام صفحه، مرورگر، دستگاه و کاربر. هر گزارش یک خطا داشته باشد، با یک تصویر صفحه اگر کمک می‌کند.

بیشتر خطاها برای فهمیدن زمان بیشتری از رفع کردن می‌برند. یک گزارش روشن بخش فهمیدن را حذف می‌کند. این موضوع با ابزارهای هوش مصنوعی اهمیت بیشتری دارد: یک هوش مصنوعی نمی‌تواند دربارهٔ اینکه منظورتان از «پرداخت عجیب است» چیست سؤال تکمیلی بپرسد، پس حدس می‌زند — و یک حدس اشتباه ممکن است چیز دیگری را خراب کند.

الگو

این را کپی کنید و پرش کنید:

عنوان: [چه چیزی مشکل دارد، کجا] — مثلاً «فرم رزرو زمان‌های بعد از ساعت ۶ عصر را رد می‌کند»

مراحل بازتولید:
1. ...
2. ...
3. ...

انتظار: [چه باید اتفاق بیفتد]
واقعیت: [به‌جایش چه اتفاقی افتاد]

پیام خطا: [متن دقیق، اگر وجود دارد]
کجا: [صفحه/نشانی، مرورگر، دستگاه، با کدام کاربر وارد شده‌اید]
چند وقت یک بار: [هر بار / گاهی / یک بار]
تصویر صفحه یا ضبط: [پیوست شده]

بقیهٔ این راهنما هر بخش را توضیح می‌دهد.

مرحلهٔ ۱: اول بازتولیدش کنید

پیش از نوشتن، سعی کنید خطا دوباره رخ دهد. یاد می‌گیرید کدام مراحل مهم‌اند و آیا هر بار اتفاق می‌افتد.

• از یک حالت تمیز شروع کنید: صفحه را رفرش کنید، یا خارج و دوباره وارد شوید.
• هر کلیک و هر چیزی که تایپ کردید را یادداشت کنید.
• سعی کنید کوتاه‌ترین مسیری را پیدا کنید که خطا را فعال می‌کند.
• یک مرورگر یا حساب دیگر را امتحان کنید. اگر فقط برای یک کاربر رخ می‌دهد، این سرنخ بزرگی است.

برای بیشتر دربارهٔ این، نحوهٔ اشکال‌زدایی اپلیکیشنی که با هوش مصنوعی ساخته شده را ببینید.

مرحلهٔ ۲: یک عنوان مشخص بنویسید

عنوان باید بگوید چه چیزی خراب است و کجا، تا کسی که فهرست را نگاه می‌کند بفهمد کدام خطاست.

مرحلهٔ ۳: مراحل دقیق را فهرست کنید

آن‌ها را شماره بزنید. تحت‌اللفظی باشید: کدام صفحه، کدام دکمه، چه چیزی را تایپ کردید.

1. با یک حساب مشتری وارد شوید (حساب آزمایشی: customer@example.com).
2. «Starter kit» را به سبد اضافه کنید.
3. کد تخفیف WELCOME10 را وارد کنید و روی Apply کلیک کنید.
4. روی Checkout کلیک کنید.

«سعی کنید با کد تسویه کنید» جزئیاتی را حذف می‌کند که اغلب مهم‌اند: کدام کاربر، کدام محصول، کدام کد، و آیا ابتدا اعمال شد.

مرحلهٔ ۴: انتظار در برابر واقعیت

این هستهٔ گزارش است. هر دو را بگویید، چون تفاوت آن‌ها همان خطاست.

• انتظار: صفحهٔ تسویه باز می‌شود و تخفیف ۱۰ درصدی در مجموع نشان داده می‌شود.
• واقعیت: دکمه یک لحظه چرخنده نشان می‌دهد، و بعد هیچ اتفاقی نمی‌افتد. بدون کد تخفیف، تسویه کار می‌کند.

بدون «انتظار»، خواننده ممکن است ندانند رفتار اشتباه است. بدون «واقعیت»، نمی‌دانند دنبال چه چیزی باشند.

مرحلهٔ ۵: خطاها را دقیق کپی کنید

پیام‌های خطا سریع‌ترین مسیر به علت هستند. آن‌ها را به‌صورت متن و عیناً کپی کنید — پارافریز نکنید.

کجا پیدایشان کنید:

• روی صفحه: هر پیامی که اپلیکیشن نشان می‌دهد.
• کنسول مرورگر: ابزارهای توسعه‌دهنده را باز کنید (F12، یا راست‌کلیک ← Inspect) و به تب Console خطوط قرمز را نگاه کنید.
• تب Network: در ابزارهای توسعه‌دهنده، درخواست ناموفق را پیدا کنید و نشانی و کد وضعیت آن را یادداشت کنید (برای مثال POST /api/checkout → 500).
• گزارش‌های سرور، اگر دسترسی دارید.

خطی مثل TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 اغلب مستقیم به مشکل اشاره می‌کند.

مرحلهٔ ۶: زمینه اضافه کنید

• کجا: نشانی صفحه، محیط (پیش‌نمایش، staging یا زنده).
• چه کسی: کدام کاربر یا نقش — مدیر، عضو، خارج‌شده.
• دستگاه و مرورگر: «Safari روی iPhone» در برابر «Chrome روی Windows» می‌تواند مهم باشد.
• داده: هر چیز غیرعادی دربارهٔ رکورد — متن خیلی بلند، کاراکترهای خاص، تعداد زیاد آیتم.
• از چه زمانی شروع شد: «بعد از تغییر امروز روی کدهای تخفیف» طلاست.
• چند وقت یک بار: هر بار، یا یک بار از ده بار.

مرحلهٔ ۷: نشانش دهید

یک تصویر صفحه با مشکل که دورش خط کشیده شده، یا یک ضبط کوتاه صفحه، ابهام را برمی‌دارد — به‌ویژه برای خطاهای چیدمان. اگر ابزار هوش مصنوعی شما تصویر می‌پذیرد، یکی پیوست کنید. هر چیز خصوصی را بِبُرید، از جمله کلیدها و داده‌های دیگران.

نوشتن گزارش خطا برای ابزار ساخت با هوش مصنوعی

همان ساختار به‌عنوان یک پرامپت هم کار می‌کند. دو افزودنی کمک می‌کند:

• بگویید چه چیزی نباید تغییر کند، تا اصلاح مشکل جدیدی ایجاد نکند.
• از آن بخواهید اصلاح را تأیید کند، نه فقط بنویسدش.

با یک حساب مشتری و با «Starter kit» در سبد و کد WELCOME10 اعمال شده، کلیک روی Checkout هیچ کاری نمی‌کند. انتظار: صفحهٔ تسویه باز شود با ۱۰٪ تخفیف از مجموع. واقعیت: یک چرخنده کوتاه، و بعد هیچ. تب network نشان می‌دهد POST /api/checkout مقدار 500 برگردانده. تسویه بدون کد کار می‌کند. علت را پیدا کن و بدون تغییر دادن روش محاسبهٔ قیمت برای سفارش‌هایی بدون کد، اصلاحش کن. سپس تسویه را با یک کد درصدی، یک کد مبلغ ثابت و بدون کد آزمایش کن.

اگر از علت مطمئن نیستید، اول تشخیص بخواهید:

هنوز کد را تغییر نده. بر اساس این گزارش، علت‌های احتمالی چیست و هر کدام را چه چیزی تأیید می‌کند؟

اشتباهات رایج

• «خراب است.» بدون مراحل، بدون نتیجهٔ مورد انتظار، چیزی برای اقدام وجود ندارد.
• چند خطا در یک گزارش. بعضی رفع می‌شوند، بعضی گم می‌شوند.
• خطاهای پارافریز‌شده. «یک چیز undefined» بخش مفید را پنهان می‌کند.
• نگفتن کاربر یا نقش. بسیاری از خطاها فقط مدیران را تحت تأثیر قرار می‌دهند، یا فقط کاربران جدید را.
• فقط توصیف اصلاحی که می‌خواهید («یک بررسی null اضافه کن») به‌جای مشکل.
• به اشتراک گذاشتن اطلاعات محرمانه در تصاویر صفحه یا لاگ‌های چسبانده‌شده.

چک‌لیست

• خطا را بازتولید کردم و کوتاه‌ترین مراحل را پیدا کردم.
• عنوان می‌گوید چه چیزی خراب است و کجا.
• مراحل شماره‌گذاری‌شده و تحت‌اللفظی هستند.
• هم انتظار و هم واقعیت بیان شده‌اند.
• پیام‌های خطا دقیق کپی شده‌اند، همراه با درخواست ناموفق و کد وضعیت.
• صفحه، محیط، کاربر، دستگاه و مرورگر آمده است.
• گفته‌ام چند وقت یک بار رخ می‌دهد و از چه زمانی شروع شد.
• یک تصویر صفحه یا ضبط پیوست شده، با داده‌های خصوصی حذف‌شده.
• هر گزارش یک خطا دارد.

گزارش خطا به عامل Mythex

در یک پروژهٔ Mythex، گزارش همان پرامپت است. چند قابلیت کمک می‌کند:

• یک تصویر صفحه پیوست کنید از پیش‌نمایش یا صفحهٔ خطا — تا ۵ فایل در هر پیام.
• /fix عامل را روی رفع یک خطا متمرکز می‌کند؛ حالت Plan به آن اجازه می‌دهد پیش از ویرایش بررسی کند.
• /test از عامل می‌خواهد جریان‌ها را در خود پیش‌نمایش بازتولید کند و آنچه می‌بیند را گزارش دهد.
• Revert to this point اصلاحی را که اوضاع را بدتر کرده برمی‌گرداند.

صفحهٔ اشکال‌زدایی با پرامپت در مستندات از همین ساختار مراحل / انتظار / واقعیت استفاده می‌کند. برای حلقهٔ اصلاح و بررسی اطراف آن، نحوهٔ تکرار روی اپلیکیشنی که با هوش مصنوعی ساخته شده را ببینید.

پرسش‌ها