Debug theo bằng chứng: báo lỗi cho AI đúng cách

Vấn đề thật

“Nút không bấm được, sửa đi.” AI đoán một nguyên nhân, sửa. Vẫn không được. AI đoán nguyên nhân khác, sửa thêm. Sau 5 vòng, code đầy những bản vá chồng lên nhau, lỗi gốc vẫn còn, và giờ có thêm lỗi mới.

Đó là debug đoán mò. Cách thoát là đưa cho AI bằng chứng: thứ nó không thể tự thấy.

Ba nguồn bằng chứng

1. Thông báo lỗi trong Console

Trên Chrome, Edge hoặc Firefox: bấm F12 (trên Mac: Cmd + Option + I), chọn tab Console. Dòng chữ đỏ là lỗi.

Ví dụ một lỗi hay gặp:

Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')
    at main.js:12:28

Bạn không cần hiểu hết. Chỉ cần biết đọc:

• Loại lỗi: TypeError, đoạn code đang làm việc với một thứ không tồn tại (null).
• Ở đâu: file main.js, dòng 12, cột 28.
• Nghĩa thường gặp: code tìm một phần tử trên trang (ví dụ nút) nhưng không thấy, do sai tên, hoặc code chạy trước khi trang tải xong.

Chép nguyên văn dòng lỗi gửi cho AI. Đừng tóm tắt “nó báo lỗi gì đó về null”.

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

Lỗi tái hiện được là lỗi đã sửa được một nửa. Ghi đúng từng bước:

1. Mở trang chủ trên điện thoại (hoặc chế độ mobile 375px trong F12)
2. Bấm nút menu (ba gạch) góc phải
3. Bấm "Bảng giá"
→ Mong đợi: menu đóng, trang cuộn tới bảng giá
→ Thực tế: trang cuộn tới bảng giá nhưng menu vẫn mở, che nửa màn hình

3. Ảnh chụp và bối cảnh

• Ảnh chụp màn hình lúc lỗi (nhiều công cụ AI nhận ảnh).
• Trình duyệt, thiết bị: “Safari trên iPhone” khác “Chrome trên máy tính”.
• Lần cuối chạy đúng là khi nào, đã sửa gì sau đó. Đây thường là manh mối quý nhất.

Mẫu báo lỗi 5 dòng

LỖI: [Một câu mô tả]
TÁI HIỆN: [Bước 1 → 2 → 3]
MONG ĐỢI: [Điều đáng ra phải xảy ra]
THỰC TẾ: [Điều đang xảy ra + thông báo lỗi nguyên văn nếu có]
BỐI CẢNH: [Trình duyệt/thiết bị; lần cuối chạy đúng; thay đổi gần nhất]

Yêu cầu: Trước khi sửa, hãy nêu 2-3 nguyên nhân có thể và cách kiểm tra từng cái.
Chỉ sửa sau khi xác định được nguyên nhân. Không sửa phần khác.

Dòng “nêu nguyên nhân trước khi sửa” ép AI chẩn đoán thay vì vá bừa.

Bẻ lái khi AI đi sai hướng

“Bẻ lái” là chặn AI lại trước khi nó sửa tiếp theo hướng sai. Dùng một trong ba câu sau, tùy tình huống:

Dừng sửa code. Liệt kê 3 nguyên nhân có thể, mỗi nguyên nhân kèm cách kiểm tra
để xác nhận hoặc loại bỏ. Chưa sửa gì cho tới khi tôi chọn.

Bản sửa vừa rồi làm hỏng [chức năng X]. Hoàn tác đúng thay đổi đó.
Sau đó giải thích vì sao thay đổi ảnh hưởng tới X trước khi đề xuất cách khác.

Bạn đang đổi cách làm lớn để sửa lỗi nhỏ. Giữ nguyên kiến trúc hiện tại.
Chỉ sửa trong file [tên file], tối đa [N] dòng thay đổi.

Câu đầu ép AI suy luận bằng bằng chứng thay vì đoán rồi vá. Hai câu sau khóa phạm vi để lỗi không lan.

Quy tắc 2 vòng

Nếu AI sửa 2 lần mà lỗi vẫn còn:

1. Dừng. Không bảo “thử lại” lần thứ ba.
2. Quay về checkpoint gần nhất chạy đúng (xem bài Git). Bỏ hết các bản vá lỗi.
3. Mở phiên mới, đưa brief, mô tả lỗi theo mẫu 5 dòng, kèm thông tin “đã thử A và B, không được”.
4. Nếu vẫn không được: cắt nhỏ. Tạo một trang thử chỉ chứa đúng phần lỗi, xem lỗi còn không.

Lý do: sau vài vòng thất bại, cuộc trò chuyện đầy giả định sai. Phiên mới sạch thường tìm ra nguyên nhân nhanh hơn.

Kiểm thử hồi quy: sửa xong phải kiểm lại cái cũ

Sửa lỗi A hay làm hỏng B (gọi là hồi quy, regression). Sau mỗi lần sửa, kiểm nhanh danh sách việc chính trong brief:

Kiểm nhanh sau khi sửa (2 phút):
[ ] Trang chủ mở được, không lỗi đỏ trong Console
[ ] Menu mobile mở/đóng được
[ ] Nút Zalo mở đúng
[ ] Lưới ảnh hiển thị đủ
[ ] Xem ở 375px không cuộn ngang

Lưu danh sách này vào NOTES.md, dùng lại mỗi lần.

Dấu hiệu AI đang sửa lòng vòng

• Nó nói “Tôi đã tìm ra nguyên nhân thật sự” lần thứ hai, thứ ba.
• Nó thêm code kiểm tra if (x !== null) khắp nơi thay vì tìm vì sao x là null.
• Nó xóa hoặc sửa test để test qua.
• Nó đổi thư viện, đổi cách làm lớn để “sửa” một lỗi nhỏ.

Thấy các dấu hiệu này: áp quy tắc 2 vòng.

Lỗi hay gặp

• Gửi ảnh chụp toàn màn hình code dài. Gửi text lỗi nguyên văn, AI đọc chính xác hơn.
• Sửa 3 lỗi một lúc. Sửa một, kiểm, checkpoint, rồi mới tới lỗi sau.
• Không ghi lại lỗi đã gặp. Lỗi hay quay lại. Ghi vào NOTES.md: lỗi gì, nguyên nhân, cách sửa.

Việc làm ngay

1. Mở website bất kỳ, bấm F12, xem tab Console. Tìm hiểu xem có dòng đỏ nào không.
2. Chép mẫu báo lỗi 5 dòng vào NOTES.md.
3. Viết danh sách “kiểm nhanh sau khi sửa” cho dự án của bạn từ tiêu chí nghiệm thu trong brief.

Tóm tắt

• Bằng chứng gồm: lỗi nguyên văn, bước tái hiện, mong đợi và thực tế, bối cảnh.
• Bắt AI chẩn đoán trước khi sửa.
• Sửa 2 lần không được: dừng, quay checkpoint, phiên mới, cắt nhỏ.
• Sửa xong phải kiểm lại các việc chính.

Prompt dùng ngay cho bài này

• Báo lỗi 5 dòng: Mẫu báo lỗi có bằng chứng, buộc AI chẩn đoán nguyên nhân trước khi sửa.
• Debug cùng AI theo bằng chứng: Biến 'sai rồi, làm lại' thành báo cáo lỗi 5 dòng để AI sửa đúng chỗ ngay lần đầu.