Một bug report tốt không phải là báo cáo "mô tả cho có" — nó là tài liệu giúp developer sửa lỗi nhanh nhất có thể, mà không cần hỏi lại QA thêm một câu nào. Với AI, bạn có thể biến hàng chục dòng log rối rắm, screenshot, và ghi chú vội trong lúc test thành một bug report mạch lạc, đầy đủ ngữ cảnh, chỉ trong vài phút. Nhưng AI không đi test giùm bạn, và nó cũng không tự nhiên biết "expected behavior" nếu bạn không cho nó biết. Bài này sẽ đi từng bước: cách dùng AI để viết report nhanh hơn, đúng hơn, và phù hợp với từng đối tượng đọc — kèm ví dụ prompt cụ thể trên một bug case thật.
Bug case xuyên suốt bài viết: checkout bị tạo đơn hàng trùng (duplicate order) khi khách hàng thanh toán bằng voucher giảm giá 100%, dẫn tới double charge trên payment gateway.
AI giúp bạn viết bug report tốt hơn, nhanh hơn như thế nào?
Vấn đề kinh điển của bug report không phải là thiếu công cụ, mà là thiếu thời gian và tính nhất quán. QA thường viết report lúc đã mệt sau một buổi test dài, nên report có xu hướng: thiếu bước, thiếu môi trường, thiếu impact, hoặc ngược lại — dài dòng nhưng không trọng tâm. AI giải quyết đúng vấn đề này: nó không thay bạn đi tìm bug, nhưng nó rất giỏi việc lấy các "nguyên liệu thô" (raw material) — log, screenshot, ghi chú — rồi cấu trúc lại thành một report chuẩn, đúng văn phong, đúng mức độ chi tiết mà developer cần.
Điểm mấu chốt: AI chỉ tốt bằng nguyên liệu bạn đưa vào. Nếu bạn chỉ gõ "checkout bị lỗi trùng đơn, sửa gấp", AI sẽ bù đắp phần thiếu bằng cách... đoán. Và một report dựa trên suy đoán của AI còn nguy hiểm hơn không có report, vì nó trông rất chuyên nghiệp nhưng có thể sai sự thật.
Mẹo: Trước khi mở AI, hãy tự hỏi "Nếu dev đọc report này mà không hỏi lại tôi câu nào, họ có đủ thông tin để bắt đầu debug không?" — nếu câu trả lời là không, đừng đưa cho AI viết, vì AI sẽ chỉ làm cho câu trả lời "không" đó trông đẹp hơn mà thôi.
Hai mode viết bug report với sự hỗ trợ của AI
Có hai cách dùng AI để viết bug report, và phân biệt được hai cách này giúp bạn không lạm dụng sai chỗ:
- Mode 1 — Dictation mode (chế độ đọc chính tả): Bạn đã điều tra xong, đã biết chính xác root cause, repro steps, impact. Bạn chỉ cần AI giúp diễn đạt lại cho mạch lạc, đúng format, đúng tone. Đây là cách dùng an toàn nhất — AI chỉ đóng vai trò biên tập (editor), không suy luận thêm.
- Mode 2 — Co-investigation mode (đồng điều tra): Bạn có logs, screenshot, network trace, nhưng chưa chốt được root cause hoặc chưa viết ra repro steps rõ ràng. Bạn đưa toàn bộ evidence cho AI, để nó giúp bạn tổng hợp pattern, đề xuất hypothesis, và cấu trúc report. Đây là cách dùng mạnh hơn nhưng rủi ro hơn — AI có thể suy luận sai nếu evidence không đủ, nên mọi kết luận AI đưa ra ở mode này đều phải được đánh dấu là "hypothesis" (giả thuyết), không phải "fact" (sự thật), cho tới khi bạn hoặc dev xác nhận.
Phần lớn bug report thực tế nằm ở mode 2 — vì đó chính là lý do bạn cần AI. Các phần tiếp theo của bài này sẽ tập trung xây dựng một prompt template cho mode 2.
Cấu trúc của một bug report sẵn sàng cho developer
Trước khi prompt AI viết report, bạn cần thống nhất bug report "chuẩn" gồm những phần nào. Một report đầy đủ cho developer thường có:
- Title — ngắn, mô tả triệu chứng + điều kiện, không phải kết luận (ví dụ: "Đơn hàng bị tạo trùng khi retry checkout với voucher 100%", không viết "Lỗi idempotency ở OrderService" — vì đó là kết luận chưa được xác nhận).
- Severity / Priority — mức độ nghiêm trọng và mức độ cần xử lý gấp.
- Environment — version, môi trường (staging/production), device, account test.
- Reproduction steps — các bước tối thiểu để tái hiện lỗi.
- Expected vs. Actual behavior — hành vi đúng theo spec, và hành vi thực tế quan sát được.
- Evidence — log, screenshot, network trace, video.
- Impact — ảnh hưởng tới user/business, để driving prioritization (quyết định độ ưu tiên).
- Root cause hypothesis (nếu có) — giả thuyết về nguyên nhân, kèm mức độ tin cậy.
- Suggested fix (tùy chọn) — gợi ý hướng sửa, không bắt buộc.
Bạn sẽ thấy các heading ở phần sau của bài (Investigation Evidence, My Investigation Findings, Bug Report Requirements, Relevant Spec, What the failing operation was trying to do) không phải là các phần trong bug report cuối cùng — mà là các field trong prompt bạn đưa cho AI, để AI có đủ nguyên liệu tạo ra 9 phần nói trên một cách chính xác.
Investigation Evidence
Đây là field đầu tiên trong prompt template: nơi bạn dán toàn bộ dữ liệu thô bạn thu thập được trong lúc test — không diễn giải, không kết luận, chỉ là bằng chứng thuần. AI cần evidence gốc để không phải "bịa" chi tiết.
Ví dụ, với bug checkout trùng đơn:
### Investigation Evidence
1. Application log (order-service), timestamp UTC:
14:02:11.203 [order-service] Received CreateOrderRequest orderRef=CO-88213 amount=0
14:02:11.210 [order-service] Payment gateway timeout after 3000ms, retrying request
14:02:14.402 [order-service] Received CreateOrderRequest orderRef=CO-88213 amount=0
14:02:14.480 [order-service] Order created: id=99381 orderRef=CO-88213
14:02:14.512 [order-service] Order created: id=99382 orderRef=CO-88213
2. Database query result:
SELECT id, order_ref, status, created_at FROM orders WHERE order_ref = 'CO-88213';
-> 2 rows returned (id 99381 và 99382), cùng order_ref, tạo cách nhau 32ms.
3. Payment gateway dashboard: 2 giao dịch capture cùng số tiền, cùng thời điểm,
khác transaction_id.
4. Screenshot: màn hình "Đặt hàng thành công" hiển thị 1 lần cho user,
nhưng email xác nhận đơn hàng gửi 2 lần (đính kèm screenshot email inbox).
5. Network trace (HAR file): request POST /api/checkout gửi 2 lần từ client,
cách nhau ~3.2s — do client tự động retry khi không nhận response trong 3s.
Evidence ở đây không nói "đây là bug do thiếu idempotency key" — nó chỉ trình bày sự thật quan sát được. Việc suy luận sẽ nằm ở field tiếp theo.
Mẹo: Luôn giữ timestamp đồng bộ (cùng timezone) trên mọi nguồn evidence bạn dán vào — log server, network trace, screenshot. AI rất dễ "khớp sai" giữa các event nếu timestamp lệch timezone, dẫn đến hypothesis sai ngay từ gốc.
My Investigation Findings
Field này khác Investigation Evidence: đây là phân tích của chính bạn — những gì bạn, với vai trò QA, đã kết nối được từ evidence. Đây là ground truth (sự thật đã được bạn xác nhận) mà AI phải tôn trọng, không được tự suy diễn ngược lại.
### My Investigation Findings
- Tôi đã tái hiện lỗi 4/5 lần khi giả lập network chậm (throttle 3G) trên
trang checkout, dùng voucher giảm 100% (amount = 0).
- Khi amount = 0, tôi nghi ngờ hệ thống bỏ qua bước gọi payment gateway thật,
nhưng log cho thấy vẫn có 2 lần gọi payment gateway — nên bug không liên
quan tới amount = 0, mà liên quan tới cơ chế retry khi timeout.
- Tôi đã thử lại với voucher giảm 50% (amount > 0) và KHÔNG tái hiện được lỗi
trong 5 lần thử — có thể vì response time nhanh hơn nên client không kịp
timeout và retry.
- Tôi chưa xác nhận được order-service có dùng idempotency key hay không —
đây là điều tôi muốn AI/dev giúp xác minh trong codebase.
Lưu ý cách viết: có việc "đã xác nhận" (retry gây trùng đơn) và có việc "chưa xác nhận" (idempotency key có tồn tại hay không). Việc phân định rõ ràng này giúp AI không lẫn giữa sự thật và điều cần điều tra thêm.
Mẹo: Viết Findings theo cấu trúc "Tôi đã kiểm chứng X" và "Tôi chưa kiểm chứng Y" tách biệt rõ ràng — nếu trộn lẫn, AI (và cả dev đọc report sau này) rất dễ hiểu nhầm một giả thuyết chưa kiểm chứng thành sự thật đã xác nhận.
Bug Report Requirements
Field cuối cùng của "khối nguyên liệu" là chỉ dẫn định dạng và ràng buộc — nói cho AI biết report cần viết theo chuẩn nào, cho ai đọc, giới hạn gì.
### Bug Report Requirements
- Output format: Markdown, tương thích với Jira issue description.
- Đối tượng đọc chính: Backend developer team Checkout.
- Ngôn ngữ: Tiếng Việt cho phần mô tả, giữ nguyên tiếng Anh cho tên field,
tên service, tên biến (orderRef, order-service, idempotency key...).
- Severity: đề xuất mức độ dựa trên impact, nhưng phải giải thích lý do,
không tự gán severity mà không lập luận.
- Root cause: CHỈ được viết dưới dạng "Hypothesis", không khẳng định là
nguyên nhân chính thức. Không được tự suy ra số dòng code hoặc tên file
cụ thể nếu không có quyền truy cập codebase.
- Không thêm bất kỳ thông tin nào ngoài Investigation Evidence và
Findings đã cung cấp. Nếu thiếu dữ kiện để viết phần nào, hãy đánh dấu
rõ "[CẦN BỔ SUNG]" thay vì suy diễn.
Đây là phần quan trọng nhất để kiểm soát AI hallucination (AI bịa thông tin). Câu lệnh "không thêm thông tin ngoài evidence đã cung cấp" và "đánh dấu rõ khi thiếu dữ kiện" là hai ràng buộc bắt buộc phải có trong mọi prompt viết bug report.
Mẹo: Luôn thêm câu ràng buộc "nếu thiếu dữ kiện, đánh dấu [CẦN BỔ SUNG] thay vì suy diễn" vào cuối mọi prompt viết report — đây là "van an toàn" rẻ nhất giúp bạn phát hiện ngay chỗ AI đang thiếu thông tin, thay vì phải dò từng câu xem AI có bịa hay không.
Dùng AI để tạo reproduction steps, expected vs. actual behavior và impact rõ ràng như thế nào?
Khi đã có đủ 3 field trên (Evidence, Findings, Requirements), bạn có thể ghép chúng vào một prompt và yêu cầu AI viết phần lõi của report: reproduction steps, expected vs. actual, và impact. Đây là phần dev đọc đầu tiên và đọc kỹ nhất, nên chất lượng ở đây quyết định report có hữu ích hay không.
Tạo reproduction steps thực sự tái hiện được lỗi
Reproduction steps do AI viết ra có một rủi ro đặc thù: AI có xu hướng viết steps "nghe hợp lý" dựa trên ngôn ngữ tự nhiên trong Findings của bạn, chứ không phải dựa trên đúng trình tự bạn đã thực hiện. Ví dụ nếu bạn viết "tôi throttle network rồi chọn voucher", AI có thể tự sắp xếp lại thứ tự thành "chọn voucher trước, throttle sau" vì nghe mượt hơn — nhưng thứ tự sai có thể khiến dev không tái hiện được lỗi.
Prompt gợi ý:
Dựa trên Investigation Evidence và Findings ở trên, viết Reproduction Steps
dạng danh sách đánh số, mỗi step là MỘT hành động cụ thể, có thể thực hiện
lại chính xác bởi người khác. Không gộp nhiều hành động vào 1 step.
Giữ đúng trình tự thời gian như trong Findings, không tự sắp xếp lại.
Nếu một điều kiện là bắt buộc để tái hiện lỗi (ví dụ: network chậm), phải
nêu rõ cách thiết lập điều kiện đó (ví dụ: throttle 3G bằng Chrome DevTools).
Ví dụ output AI trả về:
**Reproduction Steps:**
1. Mở Chrome DevTools > Network > chọn throttling "Slow 3G".
2. Đăng nhập tài khoản test, thêm sản phẩm vào cart, vào trang checkout.
3. Áp dụng voucher giảm giá 100% (mã VOUCHER100), xác nhận amount hiển thị = 0.
4. Nhấn "Đặt hàng" một lần duy nhất, không nhấn lại dù UI phản hồi chậm.
5. Quan sát: request POST /api/checkout được gửi lần 2 tự động sau ~3.2s
(do client-side retry khi không nhận response kịp).
6. Kiểm tra bảng orders trong database với order_ref tương ứng.
**Kết quả:** Bước 6 cho ra 2 record order cùng order_ref (99381, 99382).
Mẹo: Sau khi AI viết repro steps, tự thực hiện lại đúng 100% các bước đó (không tự động "hiểu ý" và bỏ bước) trước khi file report — nếu bạn không tái hiện được lỗi theo đúng steps AI viết, dev chắc chắn cũng không tái hiện được.
Neo expected behavior vào spec hoặc contract
Đây là lỗi phổ biến nhất khi để AI tự viết "Expected behavior": nếu không có spec, AI sẽ tự suy ra expected behavior nghe "hợp lý về mặt kỹ thuật" (ví dụ: "hệ thống nên tự động phát hiện và hủy đơn trùng") nhưng có thể hoàn toàn khác với yêu cầu nghiệp vụ thực tế (ví dụ: business muốn chặn request trùng ngay từ đầu, không phải hủy sau khi tạo). Expected behavior không phải là "cái gì nghe hợp lý", mà là "cái gì được spec/contract quy định". Vì vậy bạn cần thêm field Relevant Spec trước khi AI viết phần này.
Relevant Spec
Field này chứa đoạn spec, acceptance criteria, hoặc API contract liên quan trực tiếp tới hành vi đang lỗi — dán nguyên văn, không diễn giải lại.
### Relevant Spec
Trích từ tài liệu "Checkout Idempotency Requirements v2.1", mục 3.2:
"Mọi request tạo đơn hàng (CreateOrderRequest) PHẢI được gửi kèm
Idempotency-Key duy nhất cho mỗi lượt thanh toán của user. Nếu order-service
nhận nhiều request với cùng Idempotency-Key trong vòng 60 giây, chỉ request
đầu tiên được xử lý; các request sau PHẢI trả về order đã tạo trước đó,
không được tạo order mới. Client PHẢI tự động retry request khi không nhận
response trong 3 giây, sử dụng lại cùng Idempotency-Key cho lần retry."
Với spec này, AI không còn phải đoán "expected behavior là gì" — nó chỉ cần trích dẫn đúng quy định và so sánh với actual behavior quan sát được trong Evidence.
Mẹo: Nếu không có tài liệu spec chính thức, dùng chính API contract (OpenAPI/Swagger schema, mô tả field trong Postman collection) hoặc acceptance criteria trong ticket gốc làm "Relevant Spec" — miễn là đó là nguồn có thể trích dẫn được, không phải suy đoán của riêng bạn.
What the failing operation was trying to do
Field này bổ sung ngữ cảnh nghiệp vụ (business intent) — mục đích ban đầu của thao tác đang bị lỗi, để AI viết Impact statement gắn với hậu quả thật, không chỉ mô tả kỹ thuật khô khan.
### What the failing operation was trying to do
Thao tác CreateOrderRequest này nhằm ghi nhận việc khách hàng hoàn tất
thanh toán và tạo DUY NHẤT một đơn hàng tương ứng, để: (1) trừ đúng 1 lần
số lượng voucher đã dùng, (2) trừ đúng 1 lần inventory sản phẩm, (3) gửi
đúng 1 email xác nhận cho khách hàng, tránh gây nhầm lẫn hoặc double-charge.
Mẹo: Khi mô tả "what the operation was trying to do", luôn liệt kê các side-effect đi kèm (trừ kho, trừ voucher, gửi email, ghi log tài chính...) — vì impact thật của bug thường không nằm ở hành vi chính, mà nằm ở các side-effect bị lặp lại theo.
Tạo impact statement giúp quyết định độ ưu tiên
Khi đã có đủ Evidence, Findings, Relevant Spec, và business intent, bạn ghép toàn bộ vào một prompt duy nhất để AI viết Expected vs. Actual và Impact — hai phần quyết định mức độ ưu tiên xử lý.
Prompt tổng hợp:
Dựa trên Investigation Evidence, My Investigation Findings, Relevant Spec,
và "What the failing operation was trying to do" ở trên, viết:
1. Expected Behavior — trích dẫn/paraphrase đúng theo Relevant Spec, không
tự suy diễn quy định không có trong spec.
2. Actual Behavior — mô tả đúng theo Evidence, không thêm chi tiết không
có trong log/screenshot.
3. Impact — nêu ảnh hưởng cụ thể tới user và business (không chỉ mô tả kỹ
thuật), ước lượng mức độ dựa trên side-effect đã liệt kê ở phần
business intent. Đề xuất Severity kèm lý do.
Ví dụ output AI trả về:
**Expected Behavior:** Theo "Checkout Idempotency Requirements v2.1" (mục 3.2),
khi client retry request tạo đơn với cùng Idempotency-Key trong vòng 60 giây,
order-service phải trả về order đã tạo trước đó, không tạo order mới.
**Actual Behavior:** order-service tạo 2 order riêng biệt (id 99381, 99382)
cho cùng một order_ref khi client tự động retry sau timeout 3s. Payment gateway
ghi nhận 2 giao dịch capture riêng biệt.
**Impact:**
- Với voucher 100%, khách hàng có thể nhận 2 email xác nhận đơn hàng cho
1 lần thanh toán, gây nhầm lẫn và tăng ticket hỗ trợ khách hàng.
- Với voucher < 100% (amount > 0), rủi ro NGHIÊM TRỌNG HƠN: khách hàng có
thể bị double charge thật trên payment gateway — mất tiền thật.
- Voucher bị trừ 2 lần nếu logic trừ voucher gắn theo số lượng order tạo
thành công, ảnh hưởng tới báo cáo doanh thu và kho voucher.
- Đề xuất Severity: S1 (Critical) — vì có khả năng gây mất tiền thật của
khách hàng, dù tần suất tái hiện phụ thuộc điều kiện network chậm.
Mẹo: Luôn yêu cầu AI tách impact theo "trường hợp tệ nhất có thể xảy ra" (ví dụ voucher < 100% dẫn tới double charge tiền thật) ngay cả khi bạn chỉ tái hiện được ở trường hợp ít nghiêm trọng hơn (voucher 100%) — vì severity nên được đánh giá theo rủi ro tối đa, không phải theo đúng những gì bạn vừa quan sát được.
Thêm root cause hypothesis và code pointer bằng phân tích AI như thế nào?
Sau khi report có đủ repro steps, expected/actual, và impact, bạn có thể (tùy chọn — không bắt buộc) yêu cầu AI đưa thêm root cause hypothesis để dev có điểm khởi đầu debug nhanh hơn. Đây là phần rủi ro cao nhất trong toàn bộ report, vì nó động đến chuyên môn của developer — cần cẩn trọng về cách trình bày.
Một root cause hypothesis tốt trông như thế nào
Một hypothesis tốt có 3 đặc điểm: (1) được gắn nhãn rõ là giả thuyết, không phải kết luận; (2) có mức độ tin cậy (confidence level) kèm lý do; (3) có ít nhất một cách để dev tự xác minh nhanh.
**Root Cause Hypothesis (chưa xác nhận):**
Nhiều khả năng (confidence: trung bình) order-service KHÔNG áp dụng
Idempotency-Key khi tạo order — hoặc có áp dụng nhưng window kiểm tra
(dedup window) ngắn hơn 3.2s (thời gian giữa 2 request retry quan sát được
trong log). Điều này khớp với việc order_ref giống nhau nhưng order id
khác nhau ở 2 record trong database.
Cách xác minh nhanh: kiểm tra order-service có đọc header Idempotency-Key
từ request không, và nếu có, kiểm tra TTL của cache/dedup store đang dùng
để lưu key này.
Cách viết "nhiều khả năng, confidence trung bình, cách xác minh nhanh" giúp dev không cảm thấy bị áp đặt kết luận, mà được gợi ý điểm bắt đầu.
Mẹo: Luôn yêu cầu AI viết kèm "cách xác minh nhanh" ngay sau mỗi hypothesis — một hypothesis không có cách kiểm chứng chỉ là suy đoán suông, không giúp dev tiết kiệm thời gian gì cả.
Tạo code pointer một cách an toàn
Nếu bạn dùng AI agent có quyền truy cập codebase (ví dụ Claude Code, hoặc AI được kết nối repo qua MCP), bạn có thể nhờ AI tìm chính xác file/function liên quan để tăng tốc debug. Nhưng đây là nơi hallucination nguy hiểm nhất — AI không có quyền truy cập code thường sẽ "tưởng tượng" ra tên file, tên function, số dòng nghe rất thuyết phục nhưng hoàn toàn sai.
Nguyên tắc an toàn:
- Chỉ yêu cầu code pointer khi AI thực sự có quyền đọc repo (qua tool đọc file, grep, không phải chỉ dựa vào training data).
- Yêu cầu AI trích dẫn đúng path + đoạn code liên quan (không chỉ nêu tên file), để bạn tự đối chiếu.
- Nếu AI không có quyền truy cập repo, yêu cầu nó nêu từ khóa nên grep (ví dụ: "Idempotency-Key", "dedup", "CreateOrderRequest") thay vì đoán tên file.
Bạn có quyền đọc repo order-service. Hãy tìm các file/function xử lý
CreateOrderRequest và kiểm tra có logic đọc/kiểm tra Idempotency-Key hay
không. Trích dẫn đúng đường dẫn file và đoạn code liên quan (không suy
diễn nếu không tìm thấy — báo "không tìm thấy" thay vì đoán).
Mẹo: Trước khi dán code pointer AI đưa ra vào bug report, tự mở đúng file/đúng dòng đó trong IDE để xác nhận — không bao giờ copy-paste path hoặc số dòng do AI đưa ra mà không tự mắt nhìn thấy code thật ở đó.
Thêm "fix suggestion" như một phần tùy chọn
Fix suggestion là phần tùy chọn, chỉ nên thêm khi bạn đã có root cause hypothesis với confidence cao và muốn tiết kiệm thời gian cho dev. Luôn đóng khung rõ đây là gợi ý, không phải chỉ đạo.
**Suggested Fix (gợi ý, không bắt buộc):**
Đảm bảo order-service dùng Idempotency-Key làm khóa chính (hoặc unique
constraint) trong dedup store, với TTL >= thời gian client retry tối đa
(ví dụ 60s theo spec). Cân nhắc idempotency ở tầng database (unique index
trên idempotency_key) để an toàn ngay cả khi tầng application logic có bug.
Mẹo: Luôn để tiêu đề "Suggested Fix (gợi ý, không bắt buộc)" thay vì "Fix" trần trụi — cách đặt tên này giữ đúng vai trò của QA (đề xuất) và tránh việc dev cảm thấy bị chỉ định cách làm.
Prompt AI viết bug report cho đối tượng developer và stakeholder như thế nào?
Cùng một bug, nhưng developer và stakeholder (product manager, business owner) cần đọc hai bản khác nhau. Developer cần precision kỹ thuật; stakeholder cần hiểu tác động kinh doanh trong 10 giây. Viết một report chung cho cả hai thường khiến cả hai bên đều không hài lòng.
Đối tượng developer: tối đa hóa độ chính xác kỹ thuật
Với developer, giữ nguyên toàn bộ chi tiết kỹ thuật: log, stack trace, request/response payload, tên field, tên service, timestamp. Không rút gọn, không "dịch" thuật ngữ kỹ thuật sang ngôn ngữ đời thường.
Viết bản Bug Report cho Developer: giữ nguyên toàn bộ log, timestamp,
tên field kỹ thuật (orderRef, Idempotency-Key, order-service...). Không
rút gọn evidence. Văn phong: ngắn gọn, có thể dùng câu cụm (fragment),
ưu tiên liệt kê hơn văn xuôi.
Đối tượng stakeholder / product manager: tối đa hóa độ rõ ràng về nghiệp vụ
Với stakeholder, loại bỏ chi tiết kỹ thuật không cần thiết, tập trung vào: chuyện gì xảy ra (bằng ngôn ngữ nghiệp vụ), ảnh hưởng tới ai/bao nhiêu, mức độ khẩn cấp, và trạng thái xử lý.
Viết bản tóm tắt cho Stakeholder (product manager, không rành kỹ thuật):
3-5 câu, không dùng thuật ngữ kỹ thuật (tránh "idempotency key", "retry",
"timeout" — thay bằng ngôn ngữ nghiệp vụ). Tập trung vào: khách hàng bị
ảnh hưởng thế nào, rủi ro tài chính, mức độ khẩn cấp, và bước tiếp theo.
Ví dụ output:
**Tóm tắt cho Stakeholder:**
Khi khách hàng thanh toán trong điều kiện mạng chậm, hệ thống có thể ghi
nhận đơn hàng của họ hai lần thay vì một lần, và trong một số trường hợp
có thể tính phí khách hàng hai lần thật. Đây là rủi ro nghiêm trọng về mặt
tài chính và trải nghiệm khách hàng. Team kỹ thuật đã xác định được nguyên
nhân nghi vấn và đang ưu tiên xử lý ở mức Critical. Dự kiến cần xác nhận
với dev trong ngày hôm nay để đưa ra thời gian khắc phục.
Gộp cả hai vào một report có 2 section
Cách hiệu quả nhất trong thực tế là gộp cả hai vào một report duy nhất, chia rõ 2 khu vực — vừa tránh phải maintain 2 tài liệu riêng, vừa để mỗi audience tự tìm đúng phần họ cần.
Viết report gồm 2 section rõ ràng, phân tách bằng heading:
## TL;DR cho Stakeholder (3-5 câu, không thuật ngữ kỹ thuật)
## Chi tiết kỹ thuật cho Engineering (đầy đủ evidence, repro steps,
expected/actual, root cause hypothesis, code pointer nếu có)
Mẹo: Luôn đặt section "TL;DR cho Stakeholder" ở TRÊN section kỹ thuật, dù bạn viết phần kỹ thuật trước — vì trong bug tracking system, người đọc thường chỉ đọc đoạn đầu trước khi quyết định có mở rộng đọc tiếp hay không.
Điều chỉnh report cho từng bug tracking system khác nhau
Mỗi bug tracking system (hệ thống quản lý issue) có ràng buộc định dạng riêng, và AI cần được nhắc rõ đang viết cho hệ thống nào:
- Jira: hỗ trợ Markdown ở editor mới, nhưng một số instance cũ vẫn dùng wiki markup (
{code},{noformat}). Nhắc AI xác nhận version editor trước khi chọn cú pháp. - GitHub Issues: Markdown chuẩn, hỗ trợ checkbox task list (
- [ ]), mention (@username), reference issue (#123) — tận dụng để link tới PR/issue liên quan. - Linear: Markdown, tự động parse liên kết issue, hỗ trợ label và priority ngay trong text nếu dùng đúng cú pháp magic word.
- Azure DevOps / TestRail: thường có field cố định (Repro Steps, System Info tách riêng field, không phải free text) — nhắc AI xuất theo cấu trúc field-value thay vì một block Markdown liền.
Xuất report ở format phù hợp với [Jira Markdown / GitHub Markdown /
Azure DevOps field-value]. Nếu hệ thống có field cố định (System Info,
Repro Steps), tách nội dung theo đúng field đó, không gộp chung một đoạn.
Mẹo: Lưu sẵn một "system prompt" riêng cho từng bug tracking system team bạn đang dùng (Jira, Linear, GitHub...) — chỉ cần đổi phần Evidence/Findings mỗi lần dùng lại, tránh phải nhắc lại quy tắc định dạng mỗi lần prompt.
Kiểm tra chất lượng report do AI viết trước khi file
Trước khi nhấn "Submit", luôn tự chạy qua checklist sau — đây là bước không thể bỏ qua dù report do AI viết trông "hoàn hảo" tới đâu:
- Fact-check từng số liệu, timestamp, tên field — đối chiếu lại với log/evidence gốc, không tin vào việc AI "tóm tắt đúng".
- Không có file path/số dòng bị bịa — nếu report có code pointer, tự mở file xác nhận.
- Repro steps đã được tự thực hiện lại thành công — không file report với steps chưa test lại.
- Root cause được đánh dấu rõ là hypothesis, không bị AI viết thành khẳng định chắc chắn.
- Tone trung lập, không quy trách nhiệm cá nhân — kiểm tra AI không viết kiểu "dev X đã code sai", chỉ mô tả hệ thống/hành vi.
- Không có thông tin nhạy cảm bị dán nhầm vào report — số thẻ thật, email khách hàng thật, token/secret trong log — che (redact) trước khi đưa cho AI và trước khi file report.
- Format đúng với bug tracking system đang dùng.
Mẹo: Đọc lại bug report AI viết ra bằng vai trò của chính developer sẽ nhận nó — nếu có bất kỳ câu nào khiến bạn phải hỏi "ủa, sao AI biết cái này?", đó là dấu hiệu cần quay lại kiểm tra xem AI có đang suy diễn ngoài evidence bạn cung cấp hay không.