Cara Menulis Laporan Pepijat yang Baik (Untuk AI atau Pembangun)

Laporan pepijat yang baik membolehkan orang lain — pembangun atau AI — melihat masalah yang sama seperti yang anda lihat, tanpa perlu bertanya apa-apa kepada anda. Ia memerlukan tajuk yang spesifik, langkah tepat untuk menghasilkannya semula, apa yang anda jangka, apa yang sebenarnya berlaku, sebarang mesej ralat yang disalin ikut perkataan asal, dan di mana ia berlaku: halaman, pelayar, peranti dan pengguna yang mana. Satu pepijat bagi setiap laporan, dengan tangkapan skrin jika membantu.

Kebanyakan pepijat mengambil masa lebih lama untuk difahami daripada untuk diperbetulkan. Laporan yang jelas menghapuskan bahagian memahami itu. Ini lebih penting lagi dengan alat AI: AI tidak boleh bertanya soalan susulan tentang maksud anda dengan "checkout pelik", jadi ia meneka — dan tekaan yang salah boleh merosakkan perkara lain.

Templat

Salin ini dan isikan:

Tajuk: [Apa yang salah, di mana] — cth. "Borang tempahan menolak masa selepas 6 petang"

Langkah untuk menghasilkan semula:
1. ...
2. ...
3. ...

Dijangka: [apa yang sepatutnya berlaku]
Sebenar: [apa yang berlaku sebaliknya]

Mesej ralat: [teks tepat, jika ada]
Di mana: [halaman/URL, pelayar, peranti, log masuk sebagai pengguna yang mana]
Kekerapan: [setiap kali / kadang-kadang / sekali]
Tangkapan skrin atau rakaman: [dilampirkan]

Bahagian selebihnya panduan ini menerangkan setiap bahagian.

Langkah 1: Hasilkan semula dahulu

Sebelum menulis, cuba buat pepijat itu berlaku semula. Anda akan tahu langkah mana yang penting, dan sama ada ia berlaku setiap kali.

• Mulakan dari keadaan bersih: muat semula, atau log keluar dan masuk semula.
• Catat setiap klik dan setiap perkara yang anda taip.
• Cuba cari laluan yang paling pendek untuk mencetuskannya.
• Cuba pelayar atau akaun kedua. Jika ia hanya berlaku untuk seorang pengguna, itu petunjuk besar.

Untuk maklumat lanjut, lihat cara menyahpepijat aplikasi yang dibina AI.

Langkah 2: Tulis tajuk yang spesifik

Tajuk hendaklah menyatakan apa yang salah dan di mana, supaya sesiapa yang mengimbas senarai tahu pepijat yang mana satu.

Langkah 3: Senaraikan langkah tepat

Nombor langkah. Jadilah literal: halaman mana, butang mana, apa yang anda taip.

1. Log masuk sebagai pelanggan (akaun ujian: customer@example.com).
2. Tambah "Starter kit" ke dalam troli.
3. Masukkan kod diskaun WELCOME10 dan klik Apply.
4. Klik Checkout.

"Cuba checkout dengan kod" meninggalkan butiran yang selalunya penting: pengguna mana, produk mana, kod mana, sama ada ia telah digunakan dahulu.

Langkah 4: Dijangka berbanding sebenar

Ini ialah inti laporan. Nyatakan kedua-duanya, kerana perbezaan itulah pepijatnya.

• Dijangka: Halaman checkout dibuka dengan diskaun 10% dipaparkan dalam jumlah.
• Sebenar: Butang memaparkan roda pemuatan selama sesaat, kemudian tiada apa berlaku. Tanpa kod diskaun, checkout berfungsi.

Tanpa "dijangka", pembaca mungkin tidak tahu bahawa kelakuan itu salah. Tanpa "sebenar", mereka tidak tahu apa yang perlu dicari.

Langkah 5: Salin ralat dengan tepat

Mesej ralat ialah laluan terpantas ke punca. Salinnya sebagai teks, ikut perkataan asal — jangan parafrasa.

Di mana hendak mencarinya:

• Di skrin: apa-apa mesej yang dipaparkan oleh aplikasi.
• Konsol pelayar: buka alat pembangun (F12, atau klik kanan → Inspect) dan lihat tab Console untuk baris merah.
• Tab Network: dalam alat pembangun, cari permintaan yang gagal dan catat URL serta kod statusnya (contohnya POST /api/checkout → 500).
• Log pelayan, jika anda ada akses.

Baris seperti TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 selalunya menunjuk terus kepada masalahnya.

Langkah 6: Tambah konteks

• Di mana: URL halaman, persekitaran (pratonton, staging atau langsung).
• Siapa: pengguna atau peranan yang mana — admin, ahli, log keluar.
• Peranti dan pelayar: "Safari pada iPhone" berbanding "Chrome pada Windows" boleh menjadi penting.
• Data: apa-apa yang luar biasa tentang rekod — teks yang sangat panjang, aksara khas, bilangan item yang besar.
• Bila ia bermula: "selepas perubahan semalam pada kod diskaun" sangat berharga.
• Kekerapan: setiap kali, atau sekali dalam sepuluh cubaan.

Langkah 7: Tunjukkannya

Tangkapan skrin dengan masalah dibulatkan, atau rakaman skrin ringkas, menghapuskan kekaburan — terutamanya untuk pepijat susun atur. Jika alat AI anda menerima imej, lampirkan satu. Potong apa-apa yang peribadi, termasuk kunci dan data orang lain.

Menulis laporan pepijat untuk pembina AI

Struktur yang sama berfungsi sebagai prompt. Dua tambahan membantu:

• Nyatakan apa yang tidak boleh berubah, supaya pembetulan tidak menyebabkan masalah baharu.
• Minta ia mengesahkan pembetulan, bukan sekadar menulisnya.

Log masuk sebagai pelanggan, dengan "Starter kit" dalam troli dan kod WELCOME10 digunakan, klik Checkout tidak berbuat apa-apa. Dijangka: halaman checkout dibuka dengan 10% diskaun pada jumlah. Sebenar: roda pemuatan sebentar, kemudian tiada apa. Tab network menunjukkan POST /api/checkout memulangkan 500. Checkout tanpa kod berfungsi. Cari punca dan betulkan tanpa menukar cara harga dikira untuk pesanan tanpa kod. Kemudian semak checkout dengan kod peratusan, kod jumlah tetap dan tanpa kod.

Jika anda tidak pasti tentang punca, minta diagnosis dahulu:

Jangan ubah kod lagi. Berdasarkan laporan ini, apakah punca yang mungkin, dan apa yang akan mengesahkan setiap satu?

Kesilapan biasa

• "Ia rosak." Tiada langkah, tiada hasil dijangka, tiada apa untuk diambil tindakan.
• Beberapa pepijat dalam satu laporan. Ada yang diperbetulkan, yang lain hilang.
• Ralat yang diparafrasa. "Sesuatu yang undefined" menyembunyikan bahagian yang berguna.
• Terlepas pengguna atau peranan. Banyak pepijat hanya menjejaskan admin, atau hanya pengguna baharu.
• Hanya menerangkan pembetulan yang anda mahu ("tambah pemeriksaan null") dan bukannya masalahnya.
• Berkongsi rahsia dalam tangkapan skrin atau log yang ditampal.

Senarai semak

• Saya telah menghasilkan semula pepijat dan mencari langkah yang paling pendek.
• Tajuk menyatakan apa yang salah dan di mana.
• Langkah bernombor dan literal.
• Kedua-dua dijangka dan sebenar dinyatakan.
• Mesej ralat disalin tepat, dengan sebarang permintaan yang gagal dan kod status.
• Halaman, persekitaran, pengguna, peranti dan pelayar disertakan.
• Saya nyatakan kekerapannya dan bila ia bermula.
• Tangkapan skrin atau rakaman dilampirkan, dengan data peribadi dibuang.
• Satu pepijat bagi setiap laporan.

Melaporkan pepijat kepada ejen Mythex

Dalam projek Mythex, laporan itu ialah prompt. Beberapa ciri membantu:

• Lampirkan tangkapan skrin pratonton atau skrin ralat — sehingga 5 fail bagi setiap mesej.
• /fix memfokuskan ejen untuk membetulkan pepijat; mod Plan membenarkannya menyiasat sebelum menyunting.
• /test meminta ejen menghasilkan semula aliran dalam pratonton itu sendiri dan melaporkan apa yang dilihatnya.
• Revert to this point membatalkan pembetulan yang menjadikan keadaan lebih teruk.

Halaman penyahpepijatan dengan prompt dalam dokumentasi menggunakan struktur langkah / dijangka / sebenar yang sama. Untuk gelung membetulkan dan menyemak di sekelilingnya, lihat cara mengulang kerja pada aplikasi yang dibina AI.

Soalan lazim