Bài 3 — Thiết kế prompt review: đầu ra cấu trúc và tiêu chí rõ ràng

Chất lượng agent phụ thuộc phần lớn vào prompt. Một prompt mơ hồ ("hãy review đoạn code này") cho ra nhận xét lan man, trùng lặp và khó máy đọc. Mục tiêu bài này: viết prompt cho ra đầu ra cấu trúc (JSON), có mức độ nghiêm trọng, và bám tiêu chí rõ ràng.

1. Ép đầu ra dạng JSON để máy xử lý được

Bạn cần biến nhận xét thành dữ liệu để lọc, đếm, và đăng đúng dòng. Định nghĩa schema:

{
  "comments": [
    {
      "file": "src/pay.py",
      "line": 42,
      "severity": "high",
      "category": "bug",
      "message": "balance tính nhưng không kiểm tra trước khi charge",
      "suggestion": "if balance < amount: raise InsufficientFunds",
      "confidence": 0.9
    }
  ],
  "summary": "1 lỗi logic nghiêm trọng ở luồng thanh toán"
}

Trường confidence và severity sẽ là công cụ chính để hạn chế false positive ở Bài 6.

2. Prompt mẫu có tiêu chí và ràng buộc

Bạn là reviewer cấp senior. Chỉ báo cáo vấn đề THỰC SỰ trong phần code MỚI (dòng bắt đầu bằng '+').
Tiêu chí ưu tiên (theo thứ tự):
1. Lỗi logic / bảo mật (severity: high)
2. Thiếu xử lý lỗi hoặc thiếu test cho nhánh mới (medium)
3. Đặt tên / rõ ràng (low)
QUY TẮC:
- KHÔNG báo lỗi style mà linter đã lo (khoảng trắng, import order).
- Nếu không chắc chắn > 0.6, ĐỪNG báo.
- Mỗi nhận xét phải trỏ đúng file + line trong diff.
- Trả về JSON đúng schema, không thêm chữ ngoài JSON.

DIFF:
<chèn diff tại đây>

Mẹo: cung cấp cả vài dòng ngữ cảnh quanh chỗ đổi (unified diff mặc định cho 3 dòng) để LLM hiểu biến từ đâu ra.

Các bước xây prompt

• Định nghĩa schema JSON cố định cho output.
• Viết "vai trò + tiêu chí ưu tiên" rõ ràng, có thứ tự.
• Thêm quy tắc loại trừ (đừng đụng style, đừng bịa).
• Ép ngưỡng confidence tối thiểu ngay trong prompt.
• Yêu cầu chỉ nhận xét trên dòng + (code mới), tránh chê code cũ không đổi.
• Parse JSON; nếu parse lỗi, thử lại một lần với lời nhắc "chỉ trả JSON".

Khung tư duy: prompt tốt = Vai trò + Phạm vi + Tiêu chí + Ràng buộc + Định dạng

• Vai trò: senior reviewer (đặt kỳ vọng chất lượng).
• Phạm vi: chỉ code mới trong diff.
• Tiêu chí: danh sách có thứ tự ưu tiên.
• Ràng buộc: ngưỡng confidence, cấm đụng style.
• Định dạng: JSON schema cố định.

Ví dụ tinh chỉnh

Ban đầu agent hay chê "nên thêm comment giải thích" ở khắp nơi (nhiễu). Bạn thêm một dòng ràng buộc: "Chỉ đề nghị thêm comment khi logic thực sự khó hiểu, không phải mặc định." Nhiễu giảm rõ rệt. Đây là vòng lặp cải tiến điển hình: quan sát output xấu → thêm ràng buộc cụ thể.

Sai lầm thường gặp

• Để LLM trả văn xuôi tự do. Không parse được thì không lọc/đo được. Luôn ép JSON.
• Tiêu chí chung chung. "Review chất lượng" khiến model đoán; hãy liệt kê cụ thể loại lỗi cần tìm.
• Không giới hạn vào code mới. Agent chê cả code cũ không thay đổi làm PR rối và gây khó chịu.
• Quên xử lý JSON hỏng. Model đôi khi kèm lời dẫn; luôn có bước retry/parse an toàn.
• Nhồi quá nhiều tiêu chí. 15 tiêu chí ngang hàng khiến model dàn trải; ưu tiên 3–4 nhóm quan trọng nhất.

Giờ agent đã cho ra nhận xét cấu trúc. Bài 4 sẽ đưa những nhận xét đó lên đúng dòng trong PR.