Cách viết báo lỗi tốt (cho AI hoặc lập trình viên)

Một báo lỗi tốt cho phép người khác, một lập trình viên hoặc một AI, thấy đúng vấn đề bạn đã thấy mà không cần hỏi lại bạn điều gì. Nó cần một tiêu đề cụ thể, các bước chính xác để tái hiện lỗi, điều bạn mong đợi, điều thực sự xảy ra, mọi thông báo lỗi chép nguyên văn, và nơi lỗi xảy ra: trang nào, trình duyệt nào, thiết bị nào và người dùng nào. Mỗi báo cáo chỉ một lỗi, kèm ảnh chụp màn hình nếu hữu ích.

Hầu hết lỗi tốn nhiều thời gian để hiểu hơn là để sửa. Một báo cáo rõ ràng loại bỏ phần tìm hiểu đó. Điều này càng quan trọng với các công cụ AI: AI không thể hỏi lại bạn "thanh toán bị lạ" nghĩa là gì, nên nó đoán, và một phỏng đoán sai có thể làm hỏng thứ khác.

Mẫu

Sao chép và điền vào:

Tiêu đề: [Điều gì sai, ở đâu] — ví dụ "Form đặt lịch từ chối giờ sau 18h"

Các bước tái hiện:
1. ...
2. ...
3. ...

Mong đợi: [điều gì nên xảy ra]
Thực tế: [điều gì đã xảy ra thay thế]

Thông báo lỗi: [nội dung chính xác, nếu có]
Ở đâu: [trang/URL, trình duyệt, thiết bị, đăng nhập bằng người dùng nào]
Tần suất: [mỗi lần / đôi khi / một lần]
Ảnh chụp màn hình hoặc bản ghi: [đính kèm]

Phần còn lại của hướng dẫn giải thích từng phần.

Bước 1: Tái hiện lỗi trước

Trước khi viết, hãy thử làm lỗi xảy ra lần nữa. Bạn sẽ biết bước nào là quan trọng, và lỗi có xảy ra mỗi lần hay không.

• Bắt đầu từ trạng thái sạch: làm mới trang, hoặc đăng xuất rồi đăng nhập lại.
• Ghi lại từng lần nhấp và từng nội dung bạn gõ.
• Thử tìm đường đi ngắn nhất kích hoạt lỗi.
• Thử một trình duyệt hoặc tài khoản khác. Nếu lỗi chỉ xảy ra với một người dùng, đó là manh mối lớn.

Để biết thêm, xem cách gỡ lỗi ứng dụng do AI xây dựng.

Bước 2: Viết tiêu đề cụ thể

Tiêu đề nên nói rõ điều gì sai và ở đâu, để ai đó lướt qua danh sách cũng biết đó là lỗi nào.

Bước 3: Liệt kê các bước chính xác

Đánh số chúng. Hãy viết theo nghĩa đen: trang nào, nút nào, bạn đã gõ gì.

1. Đăng nhập với tư cách khách hàng (tài khoản thử nghiệm: customer@example.com).
2. Thêm "Bộ khởi đầu" vào giỏ hàng.
3. Nhập mã giảm giá WELCOME10 và nhấp Áp dụng.
4. Nhấp Thanh toán.

"Thử thanh toán bằng mã" bỏ qua những chi tiết thường quan trọng: người dùng nào, sản phẩm nào, mã nào, và mã đã được áp dụng trước chưa.

Bước 4: Mong đợi so với thực tế

Đây là phần cốt lõi của báo cáo. Hãy nêu cả hai, vì sự khác biệt chính là lỗi.

• Mong đợi: Trang thanh toán mở ra với mức giảm 10% hiển thị trong tổng tiền.
• Thực tế: Nút hiện vòng quay trong một giây, rồi không có gì xảy ra. Khi không có mã giảm giá, thanh toán hoạt động bình thường.

Không có "mong đợi", người đọc có thể không biết hành vi đó là sai. Không có "thực tế", họ không biết cần tìm gì.

Bước 5: Chép lỗi chính xác

Thông báo lỗi là con đường nhanh nhất đến nguyên nhân. Chép chúng dưới dạng văn bản, nguyên văn, đừng diễn đạt lại.

Nơi tìm chúng:

• Trên màn hình: bất kỳ thông báo nào ứng dụng hiển thị.
• Console của trình duyệt: mở công cụ dành cho nhà phát triển (F12, hoặc chuột phải → Inspect) và xem tab Console để tìm dòng màu đỏ.
• Tab Network: trong công cụ nhà phát triển, tìm yêu cầu thất bại và ghi lại URL cùng mã trạng thái (ví dụ POST /api/checkout → 500).
• Nhật ký máy chủ, nếu bạn có quyền truy cập.

Một dòng như TypeError: Cannot read properties of undefined (reading 'percent') at checkout.ts:48 thường chỉ thẳng vào vấn đề.

Bước 6: Thêm bối cảnh

• Ở đâu: URL trang, môi trường (xem trước, staging hay bản chính thức).
• Ai: người dùng hoặc vai trò nào: quản trị viên, thành viên, chưa đăng nhập.
• Thiết bị và trình duyệt: "Safari trên iPhone" và "Chrome trên Windows" có thể khác nhau.
• Dữ liệu: bất cứ điều gì bất thường về bản ghi: văn bản rất dài, ký tự đặc biệt, số lượng mục lớn.
• Bắt đầu từ khi nào: "sau thay đổi mã giảm giá hôm qua" là thông tin quý giá.
• Tần suất: mỗi lần, hay một lần trong mười lần thử.

Bước 7: Cho thấy lỗi

Ảnh chụp màn hình có khoanh vùng vấn đề, hoặc một bản ghi màn hình ngắn, loại bỏ sự mơ hồ, đặc biệt với lỗi bố cục. Nếu công cụ AI của bạn chấp nhận hình ảnh, hãy đính kèm một ảnh. Cắt bỏ mọi thứ riêng tư, bao gồm khóa và dữ liệu của người khác.

Viết báo lỗi cho công cụ xây dựng AI

Cấu trúc tương tự cũng hoạt động như một prompt. Hai điều bổ sung sẽ giúp ích:

• Nói rõ điều gì không được thay đổi, để bản sửa không gây ra vấn đề mới.
• Yêu cầu nó kiểm tra bản sửa, không chỉ viết ra nó.

Đăng nhập với tư cách khách hàng, với "Bộ khởi đầu" trong giỏ hàng và mã WELCOME10 đã được áp dụng, khi nhấp Thanh toán thì không có gì xảy ra. Mong đợi: trang thanh toán mở ra với 10% giảm trên tổng tiền. Thực tế: một vòng quay ngắn, rồi không có gì. Tab network cho thấy POST /api/checkout trả về 500. Thanh toán không có mã thì hoạt động. Tìm nguyên nhân và sửa mà không thay đổi cách tính giá cho đơn hàng không có mã. Sau đó kiểm tra thanh toán với mã phần trăm, mã số tiền cố định và không có mã.

Nếu bạn chưa chắc nguyên nhân, hãy yêu cầu chẩn đoán trước:

Chưa thay đổi mã. Dựa trên báo cáo này, các nguyên nhân có thể là gì, và điều gì sẽ xác nhận từng nguyên nhân?

Các lỗi thường gặp

• "Nó bị hỏng." Không có các bước, không có kết quả mong đợi, không có gì để hành động.
• Nhiều lỗi trong một báo cáo. Có lỗi được sửa, có lỗi bị bỏ quên.
• Lỗi bị diễn đạt lại. "Một thứ undefined nào đó" che giấu phần hữu ích.
• Thiếu người dùng hoặc vai trò. Nhiều lỗi chỉ ảnh hưởng đến quản trị viên, hoặc chỉ người dùng mới.
• Chỉ mô tả bản sửa bạn muốn ("thêm kiểm tra null") thay vì mô tả vấn đề.
• Chia sẻ bí mật trong ảnh chụp màn hình hoặc nhật ký dán vào.

Danh sách kiểm tra

• Tôi đã tái hiện được lỗi và tìm ra các bước ngắn nhất.
• Tiêu đề nói rõ điều gì sai và ở đâu.
• Các bước được đánh số và viết theo nghĩa đen.
• Đã nêu cả mong đợi và thực tế.
• Thông báo lỗi được chép chính xác, kèm yêu cầu thất bại và mã trạng thái nếu có.
• Có trang, môi trường, người dùng, thiết bị và trình duyệt.
• Tôi đã nói rõ tần suất và thời điểm bắt đầu.
• Có đính kèm ảnh chụp màn hình hoặc bản ghi, đã xóa dữ liệu riêng tư.
• Mỗi báo cáo chỉ một lỗi.

Báo lỗi cho agent của Mythex

Trong một dự án Mythex, báo cáo chính là prompt. Một vài tính năng giúp ích:

• Đính kèm ảnh chụp màn hình của bản xem trước hoặc màn hình lỗi, tối đa 5 file mỗi tin nhắn.
• /fix tập trung agent vào việc sửa lỗi; chế độ Plan cho phép nó điều tra trước khi chỉnh sửa.
• /test yêu cầu agent tái hiện các luồng ngay trong bản xem trước và báo lại những gì nó thấy.
• Quay lại thời điểm này hoàn tác một bản sửa làm mọi thứ tệ hơn.

Trang gỡ lỗi bằng prompt trong tài liệu dùng cùng cấu trúc các bước / mong đợi / thực tế. Để biết vòng lặp sửa và kiểm tra xung quanh nó, xem cách lặp lại trên ứng dụng do AI xây dựng.

Câu hỏi thường gặp