Debug Prompt — Framework xác định và sửa lỗi prompt không hoạt động

Bạn đã từng gặp tình huống viết prompt rất công phu nhưng Claude trả về kết quả lệch hoặc không như mong đợi? Đây là vấn đề phổ biến mà hầu hết người dùng AI gặp phải. Giống như việc debug code, debug prompt cũng cần một quy trình có hệ thống để xác định nguyên nhân gốc và sửa lỗi hiệu quả. Bài viết này trình bày một framework đầy đủ để bạn làm điều đó.

Các loại lỗi prompt thường gặp

Trước khi bắt tay vào debug, bạn cần nhận diện được prompt của mình đang mắc loại lỗi nào. Dưới đây là 6 loại lỗi phổ biến nhất khi làm việc với Claude.

Lỗi 1: Prompt quá mơ hồ (Vagueness)

Đây là lỗi phổ biến nhất. Prompt không cung cấp đủ ngữ cảnh hoặc không chỉ rõ kết quả mong muốn, dẫn đến Claude phải "đoán" ý định của bạn.

Ví dụ lỗi:

Hãy viết cho tôi một email.

Prompt này thiếu thông tin về: gửi cho ai, mục đích gì, giọng điệu nào, độ dài bao nhiêu. Claude sẽ tạo một email generic không có giá trị thực tế.

Đã sửa:

Viết email gửi cho khách hàng B2B SaaS (CTO level) để giới thiệu
tính năng mới của sản phẩm — tính năng auto-scaling.
Giọng điệu: chuyên nghiệp, trực tiếp, không phô trương.
Độ dài: 150-200 từ.
Kết thúc bằng CTA đặt lịch demo.

Lỗi 2: Chỉ dẫn mâu thuẫn (Contradictory Instructions)

Khi prompt chứa nhiều chỉ dẫn xung đột nhau, Claude sẽ cố gắng thỏa hiệp và kết quả thường không tốt ở bất kỳ khía cạnh nào.

Ví dụ lỗi:

Viết bài blog ngắn gọn về machine learning.
Giải thích chi tiết mọi khái niệm.
Giới hạn trong 200 từ.
Bao gồm tất cả các thuật toán phổ biến.

Ở đây có ít nhất 3 mâu thuẫn: "ngắn gọn" vs "giải thích chi tiết", "200 từ" vs "tất cả thuật toán phổ biến", và việc giải thích chi tiết mọi khái niệm trong 200 từ là bất khả thi.

Lỗi 3: Sai format đầu ra (Wrong Output Format)

Bạn muốn kết quả dạng bảng nhưng không chỉ rõ, hoặc yêu cầu format mà Claude không thể tạo trực tiếp (ví dụ: file Excel, hình ảnh).

Ví dụ lỗi:

Phân tích dữ liệu bán hàng và tạo biểu đồ.

Đã sửa:

Phân tích dữ liệu bán hàng dưới đây và trình bày kết quả theo:
1. Bảng tổng hợp theo tháng (Markdown table)
2. Nhận xét xu hướng tăng/giảm
3. Code Python dùng matplotlib để tạo biểu đồ bar chart

Dữ liệu:
[Dán dữ liệu ở đây]

Lỗi 4: Quá tải ngữ cảnh (Context Overload)

Đưa quá nhiều thông tin vào prompt khiến Claude bị "lạc" và không biết đâu là trọng tâm. Đặc biệt nghiêm trọng khi copy-paste nguyên văn tài liệu dài mà không highlight phần quan trọng. Giải pháp là tóm tắt ngữ cảnh, chỉ giữ lại phần liên quan trực tiếp đến câu hỏi, và đánh dấu rõ phần nào Claude cần tập trung.

Lỗi 5: Thiếu ví dụ mẫu (Missing Examples)

Đối với các tác vụ phức tạp hoặc có tính chủ quan (viết sáng tạo, đánh giá chất lượng), việc không cung cấp ví dụ mẫu khiến Claude không biết "chuẩn" của bạn là gì. Kỹ thuật few-shot prompting — cung cấp 2-3 ví dụ input/output mẫu — thường giải quyết vấn đề này ngay lập tức.

Lỗi 6: Giả định sai về khả năng của model (Capability Mismatch)

Yêu cầu Claude làm những việc vượt quá khả năng hiện tại — truy cập URL thời gian thực, thực thi code, hoặc nhớ thông tin từ phiên trước. Đây không phải lỗi prompt mà là lỗi kỳ vọng. Cần hiểu rõ ranh giới khả năng của model trước khi thiết kế prompt.

Framework 5 bước debug prompt

Sau khi hiểu các loại lỗi, đây là quy trình có hệ thống để debug bất kỳ prompt nào không hoạt động.

Bước 1: Reproduce — Tái tạo vấn đề

Chạy lại prompt ít nhất 3 lần để xác nhận vấn đề có tính hệ thống hay chỉ là do randomness của model. Ghi lại chính xác input và output mỗi lần.

Tôi đã chạy prompt này 3 lần và nhận kết quả như sau:

Prompt: [Dán prompt gốc]

Lần 1: [Kết quả lần 1 — tóm tắt vấn đề]
Lần 2: [Kết quả lần 2 — tóm tắt vấn đề]
Lần 3: [Kết quả lần 3 — tóm tắt vấn đề]

Vấn đề lặp lại: [Mô tả pattern chung]

Hãy giúp tôi xác định nguyên nhân prompt này
không cho kết quả mong muốn.

Nếu kết quả thay đổi nhiều giữa các lần chạy, vấn đề có thể là prompt thiếu ràng buộc cụ thể. Nếu kết quả sai giống nhau mỗi lần, vấn đề nằm ở logic hoặc cấu trúc prompt.

Bước 2: Isolate — Cô lập biến

Tách prompt thành các thành phần nhỏ và test từng phần riêng lẻ. Mục tiêu là tìm ra chính xác phần nào gây ra vấn đề.

Tôi đang debug prompt sau đây. Hãy giúp tôi phân tích
từng thành phần và xác định phần nào có vấn đề:

Prompt gốc:
"""
[Dán toàn bộ prompt]
"""

Hãy phân tích:
1. Phần mô tả vai trò (role) — có rõ ràng không?
2. Phần ngữ cảnh (context) — có đủ và không mâu thuẫn không?
3. Phần chỉ dẫn cụ thể (instructions) — có logic không?
4. Phần format đầu ra (output format) — có khả thi không?
5. Phần ràng buộc (constraints) — có xung đột không?

Với mỗi phần, đánh giá: Tốt / Cần cải thiện / Có vấn đề.
Nếu có vấn đề, giải thích cụ thể và đề xuất sửa.

Bước 3: Hypothesize — Đặt giả thuyết

Dựa trên kết quả cô lập, đặt giả thuyết về nguyên nhân gốc. Các giả thuyết thường gặp:

• Giả thuyết 1: Prompt thiếu ngữ cảnh cần thiết để Claude hiểu đúng yêu cầu
• Giả thuyết 2: Các chỉ dẫn trong prompt mâu thuẫn với nhau
• Giả thuyết 3: Format đầu ra không phù hợp với nội dung yêu cầu
• Giả thuyết 4: Prompt quá dài khiến Claude mất tập trung vào chỉ dẫn chính
• Giả thuyết 5: Thiếu ví dụ mẫu dẫn đến Claude hiểu sai tiêu chuẩn

Mỗi giả thuyết cần có thể kiểm chứng được. Nếu bạn không thể thiết kế một test để chứng minh hoặc bác bỏ giả thuyết, giả thuyết đó chưa đủ cụ thể.

Bước 4: Fix — Sửa và test

Áp dụng sửa đổi dựa trên giả thuyết và so sánh kết quả. Quan trọng: chỉ thay đổi một yếu tố mỗi lần để biết chính xác thay đổi nào tạo ra sự khác biệt.

Tôi đang A/B test hai phiên bản prompt. Hãy đánh giá cả hai
và so sánh kết quả:

Phiên bản A (gốc):
"""
Viết tóm tắt bài báo này trong 100 từ.
[Nội dung bài báo]
"""

Phiên bản B (đã sửa — thêm role và format):
"""
Bạn là một biên tập viên báo chí với 10 năm kinh nghiệm.
Tóm tắt bài báo sau theo đúng 3 đoạn:
- Đoạn 1: Thông tin chính (ai, cái gì, khi nào)
- Đoạn 2: Chi tiết quan trọng
- Đoạn 3: Ý nghĩa và tác động
Tổng cộng không quá 100 từ.

[Nội dung bài báo]
"""

So sánh: chính xác, đầy đủ, văn phong, độ dài.

Bước 5: Verify — Xác nhận trên nhiều trường hợp

Prompt đã sửa cần được test với nhiều đầu vào khác nhau để đảm bảo tính ổn định. Một prompt tốt phải hoạt động nhất quán, không chỉ với một trường hợp cụ thể.

Tôi đã sửa prompt và cần verify với nhiều trường hợp khác nhau.

Prompt đã sửa:
"""
[Dán prompt đã sửa]
"""

Hãy chạy prompt này với 3 trường hợp test khác nhau:
1. Trường hợp bình thường (typical case)
2. Trường hợp biên (edge case — input rất ngắn hoặc rất dài)
3. Trường hợp khó (complex case — nhiều thông tin, nhiều yêu cầu)

Với mỗi trường hợp, đánh giá: Pass / Fail / Partial.
Nếu Fail hoặc Partial, giải thích vấn đề cụ thể.

A/B Testing prompt có hệ thống

A/B testing không chỉ là so sánh 2 phiên bản. Để có kết quả đáng tin cậy, bạn cần một quy trình có hệ thống.

Thiết lập A/B test

Xác định rõ: biến độc lập (phần prompt thay đổi), biến phụ thuộc (metric cần đo), và điều kiện kiểm soát (những gì giữ nguyên).

Tôi cần thiết lập A/B test cho prompt sau.
Hãy giúp tôi xác định các yếu tố:

Prompt hiện tại: [Dán prompt]
Vấn đề hiện tại: [Mô tả vấn đề]

1. Biến độc lập: Phần nào của prompt sẽ thay đổi?
2. Biến phụ thuộc: Đo lường kết quả bằng tiêu chí nào?
   (độ chính xác, độ đầy đủ, giọng điệu, độ dài, ...)
3. Điều kiện kiểm soát: Những gì cần giữ nguyên?
4. Số lượng test: Cần chạy bao nhiêu lần để có ý nghĩa?
5. Tiêu chí thành công: Thế nào là "tốt hơn"?

Tạo 2-3 phiên bản thay thế để test.

Ma trận so sánh

Sau khi chạy test, tổng hợp kết quả theo ma trận để dễ so sánh:

Tiêu chí	Trọng số	Phiên bản A	Phiên bản B	Phiên bản C
Độ chính xác	40%	7/10	9/10	8/10
Độ đầy đủ	25%	6/10	8/10	9/10
Giọng điệu	20%	8/10	7/10	8/10
Độ dài phù hợp	15%	5/10	9/10	7/10
Tổng điểm	100%	6.65	8.35	8.15

Trong ví dụ này, Phiên bản B thắng với điểm tổng hợp cao nhất, đặc biệt mạnh ở độ chính xác và độ dài phù hợp.

Prompt Versioning — Quản lý phiên bản prompt

Khi làm việc nghiêm túc với prompt — đặc biệt trong môi trường production — bạn cần hệ thống quản lý phiên bản tương tự như quản lý code.

Cấu trúc phiên bản

Áp dụng quy tắc Semantic Versioning cho prompt:

• Major (v1.0 -> v2.0): Thay đổi cấu trúc prompt, đổi format đầu ra, hoặc thay đổi mục đích sử dụng
• Minor (v1.0 -> v1.1): Thêm chỉ dẫn mới, bổ sung ví dụ, tinh chỉnh giọng điệu
• Patch (v1.0.0 -> v1.0.1): Sửa lỗi chính tả, điều chỉnh từ ngữ nhỏ, fix edge case

Template ghi chép phiên bản

## Prompt: [Tên prompt]
## Phiên bản: v1.2.0
## Ngày cập nhật: 2025-01-15
## Tác giả: [Tên]

### Thay đổi so với v1.1.0:
- Thêm ví dụ mẫu cho trường hợp invoice nhiều trang
- Bổ sung ràng buộc về format số tiền (VND, không dấu phẩy)
- Sửa chỉ dẫn về xử lý trường hợp thiếu thông tin

### Lý do thay đổi:
- v1.1.0 xử lý sai invoice nhiều trang (miss trang 2+)
- Khách hàng phản hồi format số tiền không nhất quán

### Kết quả test:
- Độ chính xác: 78% -> 91%
- Edge case pass rate: 60% -> 85%

### Prompt:
"""
[Nội dung prompt đầy đủ]
"""

Lưu trữ phiên bản với Git

Cách đơn giản nhất để version control prompt là lưu trong repository Git, mỗi prompt là một file riêng:

prompts/
  invoice-extraction/
    v1.0.0.txt
    v1.1.0.txt
    v1.2.0.txt
    CHANGELOG.md
    test-cases/
      typical.json
      edge-cases.json
  email-generation/
    v1.0.0.txt
    v2.0.0.txt
    CHANGELOG.md

Với cách tổ chức này, bạn có thể dễ dàng rollback về phiên bản cũ nếu phiên bản mới có vấn đề, và theo dõi lịch sử thay đổi của từng prompt theo thời gian.

Ví dụ thực tế: Debug prompt trích xuất thông tin hóa đơn

Để minh họa quy trình 5 bước, hãy xem một trường hợp thực tế.

Vấn đề ban đầu

Prompt gốc để trích xuất thông tin từ hóa đơn:

Đọc hóa đơn này và lấy thông tin quan trọng.

Kết quả: Claude trả về một đoạn văn mô tả nội dung hóa đơn thay vì dữ liệu có cấu trúc. Thiếu nhiều trường quan trọng.

Bước 1 — Reproduce

Chạy 3 lần với 3 hóa đơn khác nhau. Kết quả đều là đoạn văn không có cấu trúc, thiếu số hóa đơn và mã số thuế. Vấn đề có tính hệ thống.

Bước 2 — Isolate

Phân tích prompt: thiếu role, thiếu định nghĩa "thông tin quan trọng", thiếu format đầu ra. Cả 3 yếu tố đều có vấn đề.

Bước 3 — Hypothesize

Giả thuyết: Prompt thiếu cụ thể về (1) những trường nào cần trích xuất và (2) format đầu ra mong muốn.

Bước 4 — Fix

Bạn là chuyên gia xử lý hóa đơn tài chính.
Trích xuất thông tin từ hóa đơn sau và trả về đúng format JSON:

{
  "so_hoa_don": "",
  "ngay_lap": "DD/MM/YYYY",
  "ben_ban": {
    "ten": "",
    "ma_so_thue": "",
    "dia_chi": ""
  },
  "ben_mua": {
    "ten": "",
    "ma_so_thue": "",
    "dia_chi": ""
  },
  "danh_sach_hang_hoa": [
    {
      "ten": "",
      "don_vi": "",
      "so_luong": 0,
      "don_gia": 0,
      "thanh_tien": 0
    }
  ],
  "tong_tien_truoc_thue": 0,
  "thue_vat": 0,
  "tong_tien_sau_thue": 0
}

Quy tắc:
- Số tiền là số nguyên (VND), không dấu phẩy
- Nếu thiếu thông tin, ghi "N/A"
- Nếu không chắc chắn, ghi giá trị kèm "[?]"

Hóa đơn:
[Dán nội dung hóa đơn]

Bước 5 — Verify

Test với 3 loại hóa đơn: hóa đơn đơn giản (2 dòng hàng), hóa đơn phức tạp (15 dòng hàng, nhiều trang), và hóa đơn scan chất lượng thấp. Kết quả: Pass/Pass/Partial (hóa đơn scan bị miss 1 dòng do mờ). Chấp nhận được — thêm chỉ dẫn xử lý ảnh chất lượng thấp vào phiên bản tiếp theo.

Prompt Quality Checklist

Sau đây là checklist để kiểm tra chất lượng prompt trước khi đưa vào sử dụng. Đánh giá từng mục theo thang Pass / Warning / Fail.

1. Clarity — Sự rõ ràng

• Mục tiêu prompt có được phát biểu rõ ràng trong 1 câu không?
• Mỗi từ trong prompt có cần thiết không? Có từ nào thừa không?
• Người khác đọc prompt có hiểu đúng ý định của bạn không?

2. Completeness — Sự đầy đủ

• Có cung cấp đủ ngữ cảnh để Claude hiểu bài toán không?
• Format đầu ra có được chỉ rõ không?
• Có ví dụ mẫu cho trường hợp phức tạp không?
• Có chỉ dẫn xử lý edge case không?

3. Consistency — Sự nhất quán

• Các chỉ dẫn có mâu thuẫn với nhau không?
• Giọng điệu yêu cầu có phù hợp với đối tượng và mục đích không?
• Các ràng buộc có khả thi cùng lúc không?

4. Constraints — Ràng buộc hợp lý

• Độ dài đầu ra có được giới hạn không?
• Có ràng buộc về format, ngôn ngữ, giọng điệu không?
• Các ràng buộc có đo lường được không?

5. Testability — Khả năng kiểm thử

• Có thể đánh giá kết quả là đúng/sai một cách khách quan không?
• Có tiêu chí thành công rõ ràng không?
• Prompt có hoạt động nhất quán khi chạy nhiều lần không?

Prompt để tự đánh giá

Hãy đánh giá prompt sau theo 5 tiêu chí (Clarity, Completeness,
Consistency, Constraints, Testability). Cho điểm 1-10 mỗi tiêu chí
và giải thích lý do.

Prompt cần đánh giá:
"""
[Dán prompt]
"""

Format kết quả:
| Tiêu chí | Điểm | Đánh giá | Đề xuất cải thiện |
|----------|------|----------|-------------------|

Điểm tổng hợp và kết luận: prompt này sẵn sàng sử dụng hay cần chỉnh sửa?

Các pattern debug nâng cao

Pattern 1: Prompt decomposition

Khi một prompt phức tạp không hoạt động, chia nó thành nhiều prompt nhỏ hơn thực hiện tuần tự. Mỗi prompt làm một việc duy nhất.

Thay vì:
"Phân tích bài viết, tóm tắt, dịch sang tiếng Anh,
và tạo 5 tiêu đề thay thế"

Chia thành 4 bước:
Bước 1: "Phân tích bài viết sau và liệt kê 5 ý chính"
Bước 2: "Dựa trên 5 ý chính, viết tóm tắt 100 từ"
Bước 3: "Dịch đoạn tóm tắt sau sang tiếng Anh"
Bước 4: "Tạo 5 tiêu đề thay thế cho bài viết có nội dung: [tóm tắt]"

Pattern 2: Progressive refinement

Bắt đầu với prompt đơn giản, sau đó thêm dần các yêu cầu. Cách này giúp bạn xác định chính xác yêu cầu nào gây ra vấn đề. Vòng 1 chỉ yêu cầu kết quả cơ bản, vòng 2 thêm format cụ thể, vòng 3 thêm ràng buộc về giọng điệu và độ dài. Nếu vấn đề xuất hiện ở vòng 3, bạn biết ngay ràng buộc mới thêm là nguyên nhân.

Pattern 3: Negative prompting

Nói cho Claude biết những gì KHÔNG nên làm, đặc biệt khi bạn gặp vấn đề cụ thể lặp đi lặp lại.

Viết email chuyên nghiệp giới thiệu sản phẩm.

KHÔNG làm những điều sau:
- Không dùng câu mở đầu "Kính gửi Quý khách hàng"
- Không liệt kê quá 3 tính năng
- Không dùng ngôn ngữ phô trương ("tốt nhất", "độc đáo", "hàng đầu")
- Không kết thúc bằng "Trân trọng"

Pattern 4: Meta-prompting

Yêu cầu Claude tự đánh giá và cải thiện prompt của bạn trước khi thực hiện. Đây là kỹ thuật mạnh mẽ để nâng cấp chất lượng prompt.

Trước khi thực hiện, hãy:
1. Phân tích prompt này và chỉ ra 3 điểm có thể cải thiện
2. Đề xuất phiên bản prompt tốt hơn
3. Thực hiện theo phiên bản đã cải thiện
4. Giải thích tại sao phiên bản mới cho kết quả tốt hơn

Xây dựng thư viện prompt đã kiểm chứng

Sau khi debug và tối ưu, lưu prompt vào thư viện để tái sử dụng. Mỗi prompt trong thư viện cần có:

• Tên và mô tả: Prompt này dùng để làm gì
• Phiên bản: Số phiên bản hiện tại
• Nội dung prompt: Prompt đầy đủ, sẵn sàng copy-paste
• Ví dụ input/output: Ít nhất 2 cặp ví dụ
• Hạn chế đã biết: Trường hợp nào prompt không hoạt động tốt
• Lịch sử thay đổi: Các thay đổi quan trọng và lý do

Lời khuyên thực tế khi debug prompt

Sau nhiều năm làm việc với prompt engineering, đây là những bài học rút ra:

• 80% lỗi prompt là do thiếu cụ thể, không phải do model kém. Trước khi nghĩ model không đủ khả năng, hãy thử viết prompt cụ thể hơn.
• Viết prompt cho người mới đọc cũng hiểu. Nếu đồng nghiệp đọc prompt của bạn mà không hiểu bạn muốn gì, Claude cũng sẽ không hiểu.
• Test với dữ liệu thật, không chỉ dữ liệu mẫu. Prompt hoạt động tốt với ví dụ đơn giản có thể fail với dữ liệu thật phức tạp hơn.
• Ghi chép mỗi lần debug. Những lỗi bạn gặp hôm nay sẽ giúp bạn tránh lỗi tương tự trong tương lai.
• Đừng cố tối ưu sớm. Bắt đầu với prompt đơn giản, chỉ thêm độ phức tạp khi cần thiết.

Bước tiếp theo

Debug prompt là kỹ năng nền tảng giúp bạn làm việc hiệu quả hơn với Claude và bất kỳ AI model nào. Khi đã thạo quy trình 5 bước này, bạn sẽ nhanh chóng xác định vấn đề và sửa lỗi thay vì thử-và-sai không có hệ thống. Tìm hiểu thêm các kỹ thuật prompt engineering nâng cao tại Thư viện Nâng cao.