Viết bug report để Dev không phải hỏi lại: mẫu và ví dụ

Một bug report tệ tốn thời gian của ba người: QA viết, Dev đọc không hiểu phải hỏi lại, QA trả lời, Dev thử tái hiện không được, lại hỏi tiếp. Một bug report tốt thì Dev đọc xong là mở code sửa được ngay.

Bài này đưa ra cấu trúc mình dùng, ví dụ trước/sau, và một cách tổ chức bug giúp Dev đỡ ngợp khi một Story có nhiều lỗi.

Cấu trúc 8 phần

1. Tiêu đề: nơi + hành vi sai + điều kiện

Tiêu đề phải đủ để người đọc hiểu lỗi mà không cần mở ra.

❌ Lỗi chart
❌ Chart không đúng khi bấm
✅ Chart Giá vàng không cập nhật khi đổi kỳ từ 1Y sang 5Y

Có thể thêm tiền tố loại lỗi như [UI], [API], [DATA] để lọc nhanh.

2. Môi trường

Staging hay production, trình duyệt và phiên bản, thiết bị/độ rộng màn hình, phiên bản build, tài khoản test (loại gói, quyền).

3. Điều kiện trước

Những gì phải có sẵn để tái hiện: đăng nhập tài khoản gói Pro, có ít nhất 1 lệnh đang chờ khớp, ngôn ngữ đặt là tiếng Anh…

4. Các bước tái hiện

Đánh số, mỗi bước một hành động, đủ chi tiết để người chưa từng dùng tính năng làm theo được.

5. Kết quả thực tế

Mô tả chính xác điều đã xảy ra. Có thông báo lỗi thì chép nguyên văn.

6. Kết quả mong đợi — kèm nguồn

Đây là phần hay bị viết qua loa nhất. “Phải hiển thị đúng” không phải là kết quả mong đợi. Hãy ghi cụ thể và dẫn nguồn: AC số mấy, frame Figma nào, API doc mục nào, hay quyết định đã chốt với BA ngày nào.

7. Bằng chứng

Ảnh chụp có khoanh vùng lỗi.
GIF hoặc video ngắn cho lỗi liên quan đến thao tác.
Request/response (dạng curl) cho lỗi API.
Lỗi trong console của trình duyệt nếu có.

8. Mức độ nghiêm trọng và ưu tiên

Hai khái niệm này hay bị nhầm:

Severity (mức độ nghiêm trọng): lỗi ảnh hưởng tới hệ thống nặng thế nào. Do QA đánh giá.
Priority (độ ưu tiên): cần sửa gấp tới đâu. Thường do PO/PM quyết định dựa trên kế hoạch.

Một lỗi chính tả trên trang chủ có severity thấp nhưng priority có thể cao. Một lỗi crash ở tính năng ít ai dùng có severity cao nhưng priority có thể thấp hơn.

Ví dụ trước và sau

Trước:

Chart bị lỗi, đổi kỳ không được. Kiểm tra lại giúp em.

Sau:

[FUNC] Chart Giá vàng không cập nhật khi đổi kỳ từ 1Y sang 5Y

Môi trường: Staging, build 2026.10.05, Chrome trên macOS, 1440px, tài khoản gói Free.

Các bước:

Mở trang Thị trường › Vàng.

Chờ chart tải xong (kỳ mặc định 1Y).

Bấm tab 5Y.

Thực tế: Tab 5Y được chọn nhưng chart vẫn hiển thị dữ liệu 1Y (trục ngày từ 10/2025). Console không có lỗi. API /prices?period=5Y trả 200 với dữ liệu đúng 5 năm.

Mong đợi: Chart vẽ lại với dữ liệu 5 năm, trục ngày từ 10/2021 (AC #4).

Bằng chứng: GIF thao tác, ảnh response API.

Severity: Major — sai thông tin hiển thị, có cách tránh là tải lại trang.

Bản sau dài hơn, nhưng Dev biết ngay lỗi nằm ở frontend (vì API trả đúng) và tái hiện được trong một phút.

Gom lỗi: một ticket mỗi lỗi hay một bug tổng hợp?

Khi test một Story mới, bạn có thể tìm thấy 10–15 lỗi nhỏ cùng loại (giao diện, dữ liệu). Tạo 15 ticket riêng khiến bảng Jira rối và Dev mất thời gian chuyển qua lại.

Một cách làm hiệu quả là gom các lỗi cùng loại của cùng một Story vào một bug tổng hợp, đánh số theo khu vực:

[UI] Tổng hợp lỗi giao diện trang Tổng quan

1. Header
  1.1 Logo lệch trái 8px so với design.
  1.2 Nút Đăng nhập dùng màu #1D4ED8, design #2563EB.
2. Card “Theo ngành”
  2.1 Tiêu đề cỡ 14px, design 16px.
3. Responsive 1280px
  3.1 Card “Theo tỉnh” tràn khỏi màn hình.

Dev sửa xong mục nào thì ghi : Fixed hoặc : Không cần fix ngay sau mục đó. Khi retest, bạn chỉ kiểm các mục đã fixed.

Khi nào vẫn nên tách ticket riêng?

Lỗi nghiêm trọng (crash, mất dữ liệu, lỗi bảo mật) cần theo dõi và ưu tiên riêng.
Lỗi thuộc phạm vi khác Story đang test.
Lỗi cần người khác sửa (team khác, bên thứ ba).

Hãy thống nhất cách làm này với team trước khi áp dụng.

Mẫu để copy

**Môi trường:** <staging/prod>, build <...>, <trình duyệt>, <độ rộng>, tài khoản <...>
**Điều kiện trước:** <...>

**Các bước:**
1. <...>
2. <...>

**Thực tế:** <...>
**Mong đợi:** <...> (nguồn: AC #<n> / Figma <link> / API doc <mục>)
**Bằng chứng:** <ảnh, GIF, curl, log>
**Severity:** <Critical/Major/Minor> — <lý do ngắn>

Kết

Bug report là sản phẩm chính mà Dev nhìn thấy từ QA. Viết tốt không chỉ giúp lỗi được sửa nhanh hơn, mà còn xây dựng niềm tin: khi Dev biết bug của bạn luôn tái hiện được và có nguồn rõ ràng, họ sẽ ưu tiên đọc bug của bạn trước.