Mẹo bug report ngắn｜Đủ để dev tái hiện, không viết tiểu thuyết【2026】

Tin nhắn hay gặp trong nhóm freelance / outsource VN:

«Anh ơi trang checkout lỗi ạ. Gấp.»

Dev mở máy — không URL, không account, không bước. Hỏi lại 3 tin → hết sprint buffer. Vấn đề không phải «thiếu template 200 dòng»; vấn đề là thiếu vài dòng đúng chỗ.

Bài này là mẹo viết ngắn: đủ để sửa, không viết tiểu thuyết. (Template outsource dài cho khách JP/US — English labels, checklist giao tiếp — nằm ở bài flagship riêng; ở đây tối ưu tốc độ ticket hàng ngày.)

Bài viết này giúp bạn

• Nhớ 4 khối bắt buộc của báo cáo ngắn
• Phân biệt «ngắn gọn» và «thiếu dữ liệu»
• Có template 60 giây copy được
• Tránh 6 lỗi làm chậm fix
• Dùng tool lấy env + format Markdown/JSON

Mục tiêu thật: tái hiện, không «tố cáo»

Bạn không cần chứng minh mình đúng. Bạn cần:

Dev làm theo bước → gặp cùng bug trong vài phút.

Nếu họ không tái hiện được, ticket chưa xong — dù bạn đã thấy lỗi 10 lần trên máy mình.

4 khối — và chỉ 4 khối «không được cắt»

1. Summary (1 câu)

Công thức: hành động → hậu quả (+ chỗ xảy ra nếu cần).

• Tốt: Mobile menu: tap «Liên hệ» trên iOS Safari → trang trắng
• Yếu: Menu lỗi / Urgent!!!

2. Steps to reproduce (đánh số)

• Bắt đầu từ trạng thái biết trước (logged out, cart trống, build X)
• Mỗi bước = một hành động quan sát được
• 3–7 bước là sweet spot; hơn 12 bước → tách precondition («cần data seed A»)

Ví dụ:

1. Mở https://staging.example.com (build 1.8.2)
2. Login `buyer-test` / role Buyer
3. Add SKU-12 vào giỏ
4. Vào Checkout, chọn VND
5. Bấm Pay

3. Expected vs Actual (đôi)

Hai cột ngắn hơn một đoạn văn. Actual nên dán message / HTTP status / screenshot UI — nguyên văn, không diễn giải.

Expected: HTTP 200, order status=paid
Actual:   HTTP 500, {"code":"PAYMENT_GATEWAY_TIMEOUT"}

4. Environment (tối thiểu)

Đủ để lọc «chỉ máy tôi»:

Game / WebGL / GPU-sensitive: thêm GPU nếu biết. Tool Kawa lấy một phần từ trình duyệt (lưu ý: GPU qua browser có thể là tên ảo ANGLE).

Bấm nút Tạo để xem báo cáo tại đây

Template 60 giây (copy)

### Summary
[Làm X] → [xảy ra Y] (trên [trang/màn])

### Steps
1.
2.
3.

### Expected
-

### Actual
- (message / status / hành vi UI)

### Environment
- OS:
- Browser/App:
- URL or build:
- Account/role: (test only)
- Repro: Always / Sometimes (n/m) / Once

### Attachments
- [ ] Screenshot / video
- [ ] Console / network (nếu có)

Dán vào GitHub Issues, Jira, Linear, hoặc Slack (bọc trong code block nếu Slack nuốt markdown).

6 lỗi làm chậm fix (dù ticket «có chữ»)

1. Không có bước — chỉ cảm xúc («lỗi rồi», «không vào được»).
2. Steps từ giữa luồng — thiếu login / thiếu data seed → «works on my machine».
3. Expected trống — dev không biết «đúng» là gì (đặc biệt bug UX).
4. Actual diễn giải — «chắc do API» thay vì status + body.
5. Env quá chung — «Chrome» không có version; mobile không ghi iOS/Android.
6. Trộn nhiều bug một ticket — checkout 500 + typo footer → tách issue.

Flaky: ghi n/m lần + điều kiện đã thử (throttle network, hard refresh, private window). Một dòng trung thực hơn đoạn «thỉnh thoảng».

Case: từ 8 tin nhắn xuống 1 ticket

Trước (chat):

A: Lỗi login
B: Browser nào?
A: Chrome
B: URL?
A: staging
B: Steps?
A: Em bấm login là nhảy

Sau (1 comment):

### Summary
Login form staging: submit email hợp lệ → redirect về `/login` (loop), không vào dashboard

### Steps
1. Mở https://staging.example.com/login (build 1.8.2)
2. Nhập `[email protected]` / password test
3. Bấm Đăng nhập

### Expected
Vào `/dashboard`, session cookie `sid` được set

### Actual
URL vẫn `/login?e=1`, console: `TypeError: Cannot read properties of undefined (reading 'token')` tại `auth.js:44`

### Environment
Win11 / Chrome 126.0.6478 / online / vi-VN
Repro: Always (5/5)

Dev reproduce được trong 2 phút — không cần hỏi lại.

Khi nào được «còn ngắn hơn»

• Typo / copy sai trên trang tĩnh: summary + URL + screenshot có thể đủ (vẫn ghi expected text).
• Crash có stack đầy đủ trong Sentry đã gắn release: link event + bước tối thiểu vẫn giúp xác nhận user path.
• Không được rút khi: thanh toán, mất dữ liệu, phân quyền, chỉ một trình duyệt/thiết bị — luôn đủ 4 khối.

Generator trên trình duyệt

1. Mở công cụ bug report
2. Xem khối môi trường tự lấy (OS/browser/màn hình… — có thể khác máy thật với GPU)
3. Điền timing / reproducibility / steps / expected / actual
4. Chọn Markdown, plain text hoặc JSON → Generate → Copy vào tracker

Chạy local trên trình duyệt, không bắt đăng ký — phù hợp dán log nội bộ (che token/PII trước khi paste công khai).

Checklist gửi ticket

• Summary một câu, không «gấp ạ» thay cho mô tả
• Steps đánh số từ trạng thái sạch
• Expected và Actual tách rõ; Actual có số liệu/nguyên văn
• Env tối thiểu đủ để lọc máy
• Repro: Always / Sometimes (n/m) / Once
• Ảnh hoặc console nếu UI / JS error
• Không nhét nhiều bug không liên quan

Liên kết liên quan

• Công cụ bug report
• Bug report template cho outsource JP/US
• Danh sách công cụ
• Bài tập thực hành