HƯỚNG DẪN THIẾT KẾ KNOWLEDGE BASE

KB DESIGN SPEC — Hướng dẫn thiết kế Knowledge Base cho AI Agent

Phiên bản: 1.0
Ngày: 2026-09-21
Đối tượng sử dụng: AI hoặc người thiết kế, đánh giá và cải tiến KB cho agent mới hoặc agent đang vận hành.

0. Chỉ thị sử dụng tài liệu

Khi được giao tài liệu này cùng yêu cầu xây dựng agent, hãy dùng nó làm hướng dẫn thiết kế KB. Không sao chép toàn bộ spec này vào KB của agent đích. Chỉ chuyển những nguyên tắc và cấu trúc phù hợp thành thiết kế cụ thể.

Mục tiêu là tạo KB giúp agent giải quyết nhiệm vụ tốt hơn năng lực nền trong cùng điều kiện, duy trì khả năng thích nghi và có thể kiểm tra, sửa đổi. Không tối ưu theo độ dài, số rule, mức độ cứng hoặc mức độ giống một chương trình.

Trước khi thiết kế, xác định nhiệm vụ, dữ liệu, công cụ và môi trường vận hành. Nếu thông tin chưa đủ, nêu giả định và tiếp tục phần không phụ thuộc; chỉ hỏi những thiếu hụt có thể làm thay đổi đáng kể kiến trúc hoặc tính đúng đắn. Không tự đặt ngưỡng chuyên môn hay chính sách rồi trình bày như sự thật.

Các từ khóa trong spec:

• BẮT BUỘC: yêu cầu thiết kế phải được đáp ứng, hoặc ghi rõ chưa đáp ứng và hệ quả.
• NÊN: mặc định khuyến nghị; có thể điều chỉnh khi có lý do phù hợp nhiệm vụ.
• CÓ THỂ: lựa chọn tùy bối cảnh.

Những từ khóa này thể hiện mức độ yêu cầu. Bản thân việc viết chúng trong văn bản không tạo cơ chế cưỡng chế kỹ thuật.

1. Mục tiêu và ranh giới của KB

KB là tập tri thức tái sử dụng phục vụ hiểu, quyết định và thực hiện nhiệm vụ trong một miền. KB có thể chứa dữ kiện, quy ước, mô hình chuyên môn, chính sách, heuristic, protocol, ví dụ và tiêu chí đánh giá.

Phân biệt các thành phần theo trách nhiệm:

Thành phần	Trách nhiệm chính
System/developer instructions	Vai trò, mục tiêu, quyền hạn, yêu cầu chung và cách sử dụng KB
KB	Tri thức miền, quy ước, tiêu chuẩn, chính sách và cách giải quyết các lớp nhiệm vụ
Tool layer	Hợp đồng công cụ, truy cập dữ liệu, thực hiện hành động, trả kết quả/lỗi
Input của case	Yêu cầu và dữ liệu riêng của nhiệm vụ hiện tại
State/memory vận hành	Đã biết gì, đã làm gì, còn thiếu gì, trạng thái và kết quả trung gian
Runtime/orchestrator, nếu có	Điều phối luồng, lưu state, kiểm tra schema, thực thi quyền và chặn hành động

Đây là phân chia trách nhiệm, không bắt buộc mỗi hàng phải là một dịch vụ hoặc file riêng. KB cũng có thể được cập nhật thường xuyên; mỗi lần chạy cần biết phiên bản hoặc thời điểm hiệu lực của nội dung quan trọng.

BẮT BUỘC xác định cách KB được đưa vào context và thẩm quyền của từng loại nội dung. Tài liệu truy xuất hoặc văn bản đầu vào không tự trở thành chỉ thị có thẩm quyền chỉ vì chứa câu mệnh lệnh. Tách nội dung policy do chủ agent phê duyệt khỏi tài liệu bên ngoài dùng làm chứng cứ.

2. Kết quả thiết kế phải đạt

Một thiết kế KB tốt cần làm rõ:

1. Agent làm nhiệm vụ nào và thế nào là thành công.
2. KB bổ sung năng lực hoặc độ tin cậy ở đâu.
3. Tri thức nào được kích hoạt trong tình huống nào.
4. Điều gì bắt buộc, điều gì chỉ là định hướng.
5. Model được tự quyết những gì.
6. Kết quả hoặc hành động được kiểm tra bằng gì.
7. Khi dữ liệu thiếu, mâu thuẫn hoặc công cụ lỗi thì xử lý thế nào.
8. Thay đổi KB sẽ được đánh giá và truy nguyên ra sao.

Không tuyên bố KB tốt hơn baseline nếu chưa có kết quả đánh giá. Nếu mới thiết kế, ghi rõ các lợi ích đang là giả thuyết cần kiểm thử.

3. Chọn nội dung: giữ phần tạo giá trị

Ưu tiên đưa vào KB:

• Tri thức đặc thù tổ chức, sản phẩm, thị trường hoặc quy trình.
• Định nghĩa chuẩn, đơn vị, quy ước và nguồn có thẩm quyền mà nhiệm vụ cần thống nhất.
• Tiêu chuẩn đúng/sai, tiêu chí lựa chọn và trade-off đặc thù.
• Những điểm model thường hiểu sai, bỏ sót hoặc phối hợp sai.
• Ràng buộc nghiệp vụ, quyền hạn và điều kiện hoàn thành.
• Heuristic chuyên môn có phạm vi áp dụng và giới hạn rõ.
• Ví dụ phân biệt những trường hợp bề ngoài giống nhau nhưng cần quyết định khác nhau.

Hạn chế:

• Bài giảng kiến thức nền không làm thay đổi hành vi hoặc chất lượng.
• Lời khuyên chung như “phân tích sâu”, “cẩn thận”, “chuyên nghiệp” mà không chỉ ra biểu hiện cần đạt.
• Nhiều cách diễn đạt trùng một yêu cầu nhưng thiếu nơi định nghĩa chính thức.
• Quy trình dự đoán mọi trường hợp khi chưa hiểu nhiệm vụ thật.

Với mỗi nội dung quan trọng, trả lời: Nó giúp agent đưa ra quyết định nào tốt hơn, tránh lỗi gì hoặc đáp ứng nghĩa vụ nào?

Không loại bỏ nội dung chỉ vì model có thể đã biết. Model biết một khái niệm không đồng nghĩa model sẽ dùng đúng quy ước, nguồn hoặc phiên bản mà nhiệm vụ yêu cầu.

Không xóa rule chỉ vì vài case không kích hoạt. Trước khi xóa, kiểm tra độ bao phủ của test và mức hậu quả của tình huống mà rule bảo vệ.

4. Các lớp nội dung và cách biểu diễn

Lớp	Nội dung	Biểu diễn thường phù hợp
Tri thức miền	Khái niệm, quan hệ, dữ kiện, quy ước	Văn bản ngắn, bảng, schema, nguồn
Tiêu chí quyết định	Khi nào chọn phương án nào	Bảng điều kiện, câu hỏi chẩn đoán, decision graph
Chính sách	Điều bắt buộc, giới hạn, quyền hạn	Rule có phạm vi, điều kiện và hệ quả
Heuristic	Cách tiếp cận thường hữu ích	Nguyên tắc, lý do, ngoại lệ, phản ví dụ
Protocol	Chuỗi công việc có điều kiện và phản hồi	Bước, state, chuyển trạng thái, recovery
Ví dụ	Cách áp dụng và phân biệt tình huống	Case đúng, case sai, case biên
Đánh giá	Thế nào là đầu ra đạt yêu cầu	Rubric, phép kiểm, validator, test case

Các lớp có thể cùng nằm trong một module nếu liên quan chặt. Mục tiêu là phân biệt ý nghĩa, không phải chia thành càng nhiều file càng tốt.

Dùng văn bản khi sắc thái và lý do quan trọng; dùng bảng/schema khi các trường lặp lại; dùng code khi cần tính toán hoặc cưỡng chế có thể thực hiện bằng máy.

Không xây DSL hoặc mini-language theo mặc định. Chỉ cân nhắc khi có cấu trúc lặp lại ổn định, ngữ nghĩa rõ và lợi ích cụ thể về phân tích cú pháp, kiểm tra, tái sử dụng hoặc thực thi.

5. Chọn mức điều khiển phù hợp từng nhiệm vụ

Các kiểu dưới đây là lựa chọn kiến trúc, không phải thang xếp hạng chất lượng:

Kiểu	Phù hợp khi	Giới hạn cần biết
KB tham chiếu	Cần tìm đúng dữ kiện, định nghĩa hoặc nguồn	Truy xuất đúng chưa bảo đảm sử dụng đúng
Framework suy luận	Nhiệm vụ mở, nhiều phán đoán	Có thể bỏ sót tiêu chí nếu không có kiểm tra
Protocol có điều kiện	Công việc có các bước và quyết định lặp lại	Có thể cứng hoặc sai ngoài phạm vi thiết kế
Đặc tả thực thi có kiểm tra	Cần state, hợp đồng dữ liệu và điều kiện chuyển bước rõ	Mức bảo đảm phụ thuộc validator/runtime thực tế

Một agent thường kết hợp nhiều kiểu: tra cứu dữ kiện, dùng framework để phân tích, dùng protocol để lấy dữ liệu, dùng runtime để kiểm soát hành động.

Không coi “càng chặt càng tốt”. Khi protocol làm chất lượng giảm, có thể sửa, thu hẹp hoặc bỏ protocol. Không mặc định phải tiếp tục làm cứng để vượt một “vùng trũng”.

6. Cân bằng ràng buộc và năng lực suy luận

Phân loại yêu cầu:

• Yêu cầu bắt buộc: điều kiện phải đáp ứng để đầu ra hoặc hành động được chấp nhận.
• Constraint: giới hạn đối với phương án hợp lệ; có thể định lượng hoặc định tính.
• Heuristic: cách làm thường hữu ích, được phép thay đổi khi tình huống không phù hợp.
• Preference: ưu tiên giữa các phương án đều hợp lệ.

Gate là điểm quyết định cho phép/chặn một bước dựa trên yêu cầu. BẮT BUỘC ghi rõ gate được model tự kiểm hay được hệ thống bên ngoài kiểm tra.

Ưu tiên quy định:

• Biến nào cần xem xét và vì sao.
• Bằng chứng nào đủ để đưa ra loại kết luận nào.
• Tiêu chí chọn hoặc loại phương án.
• Các bất biến cần giữ xuyên suốt nhiệm vụ.
• Điều kiện dừng, đổi hướng hoặc hỏi thêm.

Để model lựa chọn chiến lược, tổng hợp, giải thích và thích nghi trong phạm vi hợp lệ. Chỉ cố định thứ tự khi có quan hệ phụ thuộc, yêu cầu nghiệp vụ hoặc bằng chứng rằng thứ tự đó có ích.

Không buộc model viết toàn bộ chuỗi suy nghĩ. Yêu cầu sản phẩm trung gian hữu ích: dữ kiện, giả định, phép tính, lựa chọn, lý do ngắn gọn và kết quả kiểm tra.

Tình huống biên không tự động được giao hoàn toàn cho suy luận tự do. Xác định mức hậu quả để quyết định cần rule, kiểm tra, hỏi người dùng hay cho phép model tự xử lý.

7. Thiết kế rule có thể vận hành

Một rule vận hành cần có phạm vi áp dụng, điều kiện kích hoạt và hệ quả rõ. Không bắt buộc mọi rule phải có con số hoặc hành vi cấm.

Mẫu tối thiểu:

ID:
Mục đích:
Phạm vi / khi nào áp dụng:
Điều kiện kích hoạt:
Hành vi hoặc thay đổi trạng thái yêu cầu:
Cách kiểm tra:
Ngoại lệ / khi không áp dụng:
Nguồn hoặc lý do tồn tại:

Với rule quan trọng, bổ sung:

Đầu vào và phụ thuộc:
Mức độ: bắt buộc / heuristic / preference
Ưu tiên và cách xử lý xung đột:
Mức thực thi: model tự kiểm / kiểm tra ngoài / runtime chặn
Nếu điều kiện chưa xác định được:
Nếu thực hiện thất bại:
Case kiểm thử liên quan:
Phiên bản / ngày hiệu lực:

Ví dụ yếu:

Hãy kiểm tra kỹ dữ liệu và không kết luận thiếu căn cứ.

Ví dụ cụ thể hơn:

Trước khi so sánh hai chỉ số, xác nhận định nghĩa, kỳ đo và đơn vị có tương thích. Nếu không tương thích, chuẩn hóa khi có đủ thông tin; nếu chưa thể chuẩn hóa, nêu điểm không tương thích và không trình bày chênh lệch như một so sánh tương đương.

Ví dụ trên vẫn cần phép kiểm bên ngoài nếu hệ thống muốn ngăn chắc việc xuất một so sánh không hợp lệ.

Mọi ngưỡng chuyên môn phải có căn cứ, phạm vi và đơn vị. Nếu là tham số đề xuất chưa được duyệt hoặc kiểm chứng, gắn nhãn rõ và không dùng như chính sách chính thức.

8. Module, quyền quyết định và xung đột

Mỗi module cần xác định trách nhiệm, đầu vào, đầu ra và phụ thuộc. Không để module đồng thời âm thầm thay đổi những biến ngoài trách nhiệm của nó.

Với mỗi biến quyết định quan trọng, chỉ rõ nơi chịu trách nhiệm chốt giá trị. Nhiều module có thể cung cấp bằng chứng hoặc đề xuất, nhưng cách hợp nhất phải rõ.

Khi nhiều rule cùng áp dụng:

1. Xác định chúng có thực sự xung đột hay đang tác động các khía cạnh khác nhau.
2. Áp dụng thứ tự ưu tiên theo thẩm quyền, phạm vi hoặc ngày hiệu lực đã được định nghĩa.
3. Nếu cần tổng hợp, định nghĩa phép tổng hợp phù hợp ý nghĩa biến.
4. Nếu không thể giải quyết hợp lệ, giữ trạng thái xung đột và xử lý theo chính sách.

Không dùng mặc định min, max, worst_of hoặc “nghiêm ngặt nhất” cho mọi biến. Những phép này chỉ hợp lệ khi miền giá trị và ý nghĩa nghiệp vụ cho phép.

Phòng tránh đếm trùng: nhiều rule có thể cùng phản ánh một nguyên nhân rủi ro. Trước khi cộng dồn hệ quả, kiểm tra sự phụ thuộc và trùng lặp.

9. State, phụ thuộc và vòng lặp thực hiện

Chỉ thiết kế state machine khi nhiệm vụ có nhu cầu theo dõi trạng thái thực sự. Không thêm state chỉ để tài liệu trông chặt chẽ.

Nếu cần state, định nghĩa:

• Tên và ý nghĩa từng trường.
• Nguồn tạo, nơi lưu và nơi được phép cập nhật.
• Các giá trị hợp lệ; có trạng thái bất định hoặc không áp dụng khi cần.
• Điều kiện chuyển trạng thái và hành động tương ứng.
• Điều kiện hoàn thành, thất bại và chờ thông tin.

Enum đóng phù hợp với trạng thái điều khiển có miền giá trị hữu hạn. Không ép mọi nhận định chuyên môn thành nhãn đóng. Nếu cần UNKNOWN, CONFLICT hoặc NOT_APPLICABLE, định nghĩa hành vi đi kèm thay vì ép PASS/FAIL.

Khi dữ kiện thay đổi, đánh dấu và đánh giá lại các kết quả phụ thuộc. Chỉ cập nhật những phần bị ảnh hưởng. Việc đánh giá lại có thể cho cùng kết quả; với kết luận quan trọng, lưu căn cứ ngắn gọn.

Nếu có vòng lặp, định nghĩa điều kiện dừng, ngân sách tài nguyên và hành vi khi không có tiến triển. Nếu công cụ có tác dụng phụ, xử lý khả năng hành động đã thành công một phần trước khi retry để tránh thực hiện trùng.

10. Chứng cứ, giả định và độ bất định

Phân biệt tối thiểu:

Loại	Cách sử dụng
Dữ kiện từ nguồn	Ghi nguồn, thời điểm và giới hạn; nguồn vẫn có thể sai
Kết quả suy ra hoặc tính toán	Gắn với đầu vào, công thức/phương pháp và giả định
Ước tính	Nêu cơ sở và độ bất định phù hợp; dùng dải/kịch bản khi cần
Giả định	Được dùng cho phân tích điều kiện, không được biến thành dữ kiện đã xác minh
Chưa xác minh	Chỉ dùng trong phạm vi chính sách cho phép, không âm thầm nâng thành bằng chứng chắc chắn

Không cần gắn nhãn mọi câu. Ưu tiên claim có ảnh hưởng đến quyết định, số liệu và kết luận trọng yếu.

Phân biệt nguyên nhân thiếu dữ liệu: chưa tìm, tìm chưa thấy, nguồn không công bố, không truy cập được, trích xuất thất bại, hoặc không áp dụng. Mỗi trạng thái có thể yêu cầu hành động khác nhau.

Không tìm thấy chỉ chứng minh kết quả tìm kiếm trong phạm vi đã kiểm tra. Chỉ kết luận không tồn tại khi có cơ sở về độ đầy đủ của phạm vi và nguồn.

Khi nguồn mâu thuẫn, xét thẩm quyền, định nghĩa, thời điểm, phạm vi và chất lượng. Không mặc định nguồn mới hơn luôn đúng hơn.

Khi kết quả lệch xa mốc tham chiếu, kiểm tra dữ liệu, đơn vị, giả định, phương pháp và chính mốc tham chiếu. Không tự ép kết quả về đồng thuận, cũng không mặc định mình đúng vì đã theo protocol.

Không dùng điểm confidence như xác suất đúng nếu chưa có hiệu chuẩn. Có thể mô tả độ bất định bằng chất lượng chứng cứ, mức thiếu dữ liệu, độ nhạy và các giả định còn mở.

11. Truy xuất và ngân sách context

NÊN tổ chức theo một lõi ngắn cùng các module chỉ nạp khi liên quan:

• Lõi: phạm vi, nguyên tắc chung, thuật ngữ thiết yếu, điều phối và tham chiếu module.
• Module nhiệm vụ: tri thức, rule, ví dụ và tiêu chí kiểm tra của một lớp nhiệm vụ.
• Nguồn tham chiếu: tài liệu dài, dữ liệu và chứng cứ cần tra cứu.

Mỗi module có mô tả “dùng khi nào”, phạm vi và phụ thuộc. Khi truy xuất một rule, cần mang theo các điều kiện và ngoại lệ thiết yếu; không cắt chúng ra khỏi rule.

Tránh chỉ truy xuất theo giống từ khóa. Truy xuất cần xét nhiệm vụ hiện tại, quyết định cần đưa ra và trạng thái công việc.

Ưu tiên rõ nghĩa trước khi nén cú pháp. Ký hiệu chỉ hữu ích khi model hiểu ổn định và người bảo trì đọc được. Không dựa vào việc đặt rule ở đầu/cuối tài liệu như một bảo đảm tuân thủ.

Giữ một nơi định nghĩa chính thức cho mỗi policy. Các nơi khác tham chiếu; nếu nhắc lại để tăng khả năng sử dụng, cần tránh tạo bản sao lệch phiên bản.

Kiểm thử cả việc tìm đúng module và việc áp dụng đúng nội dung. Hai loại lỗi này cần hai cách sửa khác nhau.

12. Phân biệt hướng dẫn, kiểm tra và cưỡng chế

BẮT BUỘC mô tả đúng khả năng thực tế:

Mức	Cơ chế	Có thể khẳng định
Chỉ dẫn	Model đọc và tự làm theo	Hành vi được yêu cầu; cần đo tỷ lệ tuân thủ
Kiểm tra	Validator hoặc bộ đánh giá kiểm tra sản phẩm	Một số vi phạm có thể được phát hiện trong phạm vi phép kiểm
Cưỡng chế	Runtime kiểm soát việc chuyển bước hoặc thực hiện hành động	Vi phạm điều kiện đã được kiểm tra có thể bị chặn tại điểm đó

Schema validation kiểm tra hình dạng và một số ràng buộc dữ liệu; không tự xác minh sự thật của nội dung. Model tự báo PASS không tương đương bằng chứng độc lập.

Với mỗi yêu cầu trọng yếu, ghi:

Yêu cầu → bằng chứng cần có → phép kiểm → nơi thực thi → xử lý khi không đạt

Nếu môi trường chỉ cho phép đính kèm file KB vào chat, hãy thiết kế protocol rõ, các sản phẩm trung gian và bước tự kiểm phù hợp; công khai giới hạn về cưỡng chế. Không hứa rằng file văn bản đã trở thành engine deterministic.

Nếu có runtime, ưu tiên giao phép tính xác định, validation, quyền công cụ và trạng thái bền vững cho thành phần có thể kiểm tra bằng máy. Model đảm nhiệm phần cần hiểu ngữ nghĩa và phán đoán, với kiểm tra phù hợp mức hậu quả.

Log hữu ích gồm phiên bản KB, input liên quan, nguồn, kết quả tool, quyết định, rule đã áp dụng, state và kết quả kiểm tra. Lời giải thích do model tạo chỉ là một phần của log, không phải bằng chứng rằng mọi bước đã thực sự xảy ra.

13. Quy trình thiết kế KB cho agent mới

Bước 1 — Xác định nhiệm vụ và môi trường

Ghi nhiệm vụ chính, người dùng, loại input/output, công cụ, khả năng lưu state, cách nạp KB, ràng buộc và tiêu chí thành công. Xác định phần nào cần đúng tuyệt đối theo quy định, phần nào chấp nhận phán đoán.

Bước 2 — Thiết lập baseline

Chạy agent với chỉ dẫn nhiệm vụ tốt và điều kiện công cụ/dữ liệu tương đương, chưa có phần KB cần đánh giá. Zero-shot có thể là một baseline bổ sung, không phải thước đo duy nhất.

Chọn case thường gặp, case khó và case có hậu quả lớn. Lưu cấu hình model, prompt, tool, dữ liệu và output để so sánh công bằng.

Bước 3 — Tìm khoảng trống và nguyên nhân

Phân loại lỗi: thiếu tri thức, truy xuất sai, dữ liệu sai/thiếu, áp dụng sai, xung đột rule, mất state, tính toán sai, tool lỗi hoặc tiêu chí nghiệm thu không rõ.

Không mặc định mọi lỗi cần thêm rule. Có lỗi cần sửa nguồn, công cụ, schema, routing hoặc yêu cầu đầu vào.

Bước 4 — Thiết kế phần bổ sung tối thiểu

Chọn nội dung và hình thức phù hợp từng khoảng trống. Kết hợp thiết kế từ mục tiêu/rủi ro với học từ lỗi thực tế. Một nguyên tắc khái quát có thể xử lý nhiều ca lỗi.

Nêu rõ vùng model được tự quyết, chính sách bắt buộc và giới hạn áp dụng. Không formalize toàn bộ miền trước khi có bằng chứng cần thiết.

Bước 5 — Thiết kế kiểm tra cùng lúc

Với mỗi rule quan trọng, tạo case kích hoạt, case không nên kích hoạt, case thiếu dữ liệu để quyết định và case có xung đột nếu liên quan. Xác định kỳ vọng bằng tiêu chí quan sát được.

Bước 6 — Thử nghiệm và kiểm tra hồi quy

So với baseline và phiên bản trước. Đánh giá cả lợi ích lẫn lỗi mới. Dùng case chưa dùng để viết rule nhằm tránh tối ưu chỉ cho những ví dụ quen thuộc.

Bước 7 — Đóng gói và vận hành

Đặt ID/version, ghi nguồn, phụ thuộc và trạng thái đã kiểm chứng. Cung cấp hướng dẫn nạp, cập nhật, quan sát lỗi và rollback. Giữ lại các hạn chế chưa giải quyết.

14. Đánh giá và nghiệm thu

Chọn thước đo theo nhiệm vụ, không dùng một checklist để tự phong “cấp độ”.

Các nhóm thước đo có thể gồm:

• Độ đúng và hữu ích của kết quả.
• Tỷ lệ hoàn thành nhiệm vụ.
• Tỷ lệ lỗi nghiêm trọng hoặc vi phạm chính sách.
• Tỷ lệ từ chối/hỏi thêm không cần thiết.
• Tính nhất quán trên tiêu chí quan trọng; không yêu cầu câu chữ giống nhau.
• Khả năng xử lý dữ liệu thiếu, mâu thuẫn và sự cố tool.
• Chi phí token, số lần gọi tool, thời gian và công sức bảo trì.

NÊN dùng kết hợp:

• Case đại diện công việc thật.
• Case biên, đối kháng và xung đột.
• Thử đổi cách diễn đạt input hoặc thêm thông tin không liên quan.
• Chạy lặp khi cần đánh giá độ biến thiên.
• Tắt từng module để kiểm tra đóng góp của nó.
• Đánh giá trên case mới chưa dùng để sửa KB.

Không coi model tự chấm là nguồn đánh giá duy nhất cho yêu cầu trọng yếu. Dùng phép kiểm xác định, dữ liệu chuẩn hoặc người có chuyên môn khi phù hợp.

Lưu baseline cũ để so sánh lịch sử, nhưng chạy lại khi model, tool hoặc môi trường thay đổi. Không coi output của baseline là đáp án đúng.

Nếu chưa chạy được test, bàn giao kế hoạch kiểm thử và trạng thái CHƯA KIỂM CHỨNG, không bịa số liệu đánh giá.

15. Các sai lầm cần chủ động tránh

Sai lầm	Hướng sửa
Nhồi tri thức nền	Giữ phần có tác dụng cụ thể hoặc cần làm chuẩn
Xóa mọi định nghĩa vì model đã biết	Giữ quy ước và ý nghĩa chuẩn của nhiệm vụ
Dùng khuôn output thay cho chất lượng phân tích	Định nghĩa tiêu chí nội dung và bằng chứng
Quy định mọi bước suy luận	Giữ điểm quyết định và ràng buộc cần thiết, mở chiến lược
Framework quá chung	Bổ sung tiêu chí phân biệt, điều kiện áp dụng và ví dụ biên
Càng lỗi càng thêm rule	Tìm nguyên nhân gốc và hợp nhất rule cùng mục đích
Coi MUST hoặc YAML là cưỡng chế	Chỉ rõ nơi kiểm tra và chặn thực tế
Ngưỡng cụ thể nhưng không có căn cứ	Gắn nguồn, phạm vi hoặc nhãn tham số đề xuất
Nhiều module tự sửa cùng kết quả	Chỉ định nơi chốt và cách hợp nhất
Luôn chọn kết quả nghiêm ngặt nhất	Dùng logic phù hợp ý nghĩa nghiệp vụ
Ép mọi case ra kết luận đầy đủ	Có kết quả một phần, bất định hoặc chưa đủ dữ liệu
Tự báo đã kiểm tra là coi như đạt	Yêu cầu sản phẩm kiểm tra và bằng chứng quan sát được
Protocol phức tạp hơn nhưng chưa tốt hơn	Đo với baseline, thu hẹp hoặc loại bỏ nếu cần
Vá đúng case cũ	Thêm case mới và kiểm tra khả năng khái quát

16. Hợp đồng bàn giao cho AI thiết kế KB

Khi nhận nhiệm vụ thiết kế theo spec này, hãy bàn giao các phần sau với độ chi tiết tương xứng quy mô:

1. Tóm tắt thiết kế: nhiệm vụ, môi trường, giả định, tiêu chí thành công và phạm vi KB.
2. Bản đồ trách nhiệm: nội dung nào thuộc KB, system instructions, tools, state hoặc runtime; tránh yêu cầu một thành phần làm việc nó không thể làm.
3. Kiến trúc KB: module, mục đích, khi nào nạp và quan hệ phụ thuộc. Giải thích lựa chọn quan trọng.
4. Nội dung KB dùng được: viết các module cụ thể, không chỉ đưa tên mục hoặc dàn ý chung. Nếu thiếu nguồn chuyên môn, đánh dấu phần cần bổ sung thay vì tự bịa.
5. Hướng dẫn tích hợp ngắn: cách agent chọn và dùng module, xử lý thiếu thông tin, kiểm tra kết quả và ghi state khi cần.
6. Bảng yêu cầu trọng yếu: cách kiểm tra, mức thực thi thực tế và xử lý khi không đạt.
7. Bộ case nghiệm thu: input hoặc mô tả case, hành vi mong đợi, lỗi cần phát hiện và tiêu chí đạt. Không cần đáp án mẫu cố định cho nhiệm vụ mở.
8. Báo cáo trạng thái: đã kiểm thử gì, chưa kiểm thử gì, hạn chế và việc cần làm tiếp.

Với agent đơn giản, các phần trên có thể gộp trong một file. Với agent lớn, tách theo module có trách nhiệm rõ; không tạo nhiều file chỉ để đáp ứng hình thức.

Không tự nhận thiết kế đã trở thành execution engine vì có enum, state hoặc gate trong văn bản. Chỉ mô tả những gì hệ thống triển khai thực sự hỗ trợ.

17. Mẫu khởi động cho người giao nhiệm vụ

Có thể đính kèm file này cùng yêu cầu dưới đây:

Hãy thiết kế KB cho agent theo KB_DESIGN_SPEC.md.

Agent cần làm:
Người dùng và bối cảnh:
Input thường có:
Output mong muốn:
Công cụ và dữ liệu có thể dùng:
Cách triển khai: [chỉ prompt + file KB / có retrieval / có runtime / chưa rõ]
Ràng buộc hoặc lỗi không chấp nhận:
Tài liệu chuyên môn và ví dụ hiện có:

Hãy xác định kiến trúc phù hợp, biên soạn KB dùng được và bộ case nghiệm thu.
Nếu thông tin thiếu, ghi giả định và hỏi những điểm làm thay đổi thiết kế.
Không tự đặt chính sách hoặc ngưỡng chuyên môn thành sự thật.
Không thêm độ phức tạp nếu chưa chỉ ra nó giải quyết vấn đề gì.
Phân biệt rõ nội dung hướng dẫn model với kiểm tra/cưỡng chế thực tế.

18. Nguyên tắc kết thúc

KB trưởng thành là KB có đóng góp rõ cho công việc, được sử dụng đúng lúc, giữ được các yêu cầu quan trọng và cho phép phát hiện, sửa lỗi. Tăng độ trưởng thành bằng chứng cứ vận hành và khả năng bảo trì; không mặc định bằng thêm nội dung, thêm bước hoặc thêm ràng buộc.