Sinh docs mới chỉ giải quyết một nửa. Nửa còn lại — và là giá trị lớn nhất của agent — là giữ docs không lỗi thời. Bài này ta xây bước Verify: phát hiện khi docs lệch code.
Hai loại kiểm tra: rẻ (deterministic) trước, đắt (LLM) sau
Nguyên tắc vàng: kiểm tra bằng luật cứng (không cần LLM) trước, chỉ dùng LLM cho phần cần suy luận. Vừa rẻ vừa chắc.
Kiểm tra deterministic (không tốn token)
So sánh trực tiếp giữa AST và docstring:
import ast, re
def check_param_drift(fn_source):
tree = ast.parse(fn_source)
fn = tree.body[0]
real_args = {a.arg for a in fn.args.args}
doc = ast.get_docstring(fn) or ""
# Trich cac tham so duoc mo ta trong docstring kieu Google
doc_args = set(re.findall(r"^\s*(\w+)\s*\(", doc, re.M))
missing = real_args - doc_args # tham so co trong code, thieu trong docs
extra = doc_args - real_args # tham so bia, khong co trong code
return {"missing": missing, "extra": extra}
Chỉ với đoạn này bạn bắt được phần lớn drift kiểu "thêm tham số quên sửa docs".
Kiểm tra bằng LLM (cho phần ngữ nghĩa)
Luật cứng không bắt được "mô tả hành vi sai" (ví dụ docstring nói "trả về list" nhưng code trả về dict, hoặc mô tả logic đã đổi). Đây là lúc dùng LLM:
JUDGE = (
"Doi chieu docstring voi ma nguon. Liet ke moi diem docs MO TA SAI "
"so voi code (hanh vi, kieu tra ve, dieu kien loi). Neu khop, tra ve OK."
)
Các bước xây bộ phát hiện drift
- Với mỗi hàm, chạy
check_param_drift(rẻ) trước. - Nếu có
missing/extra→ gắn cờ drift ngay, không cần LLM. - Nếu qua bước 1, gửi hàm + docstring cho LLM-judge kiểm ngữ nghĩa.
- Gộp kết quả thành báo cáo: file, hàm, loại drift, mức nghiêm trọng.
- Với README: so
.env.examplevs bảng env, so lệnh install vs file cấu hình. - Xuất báo cáo drift (JSON) để bước Deliver dùng.
Dùng git diff để thu hẹp phạm vi
Đừng quét cả repo mỗi lần. Chỉ kiểm tra hàm nằm trong file đã đổi ở commit/PR:
git diff --name-only origin/main...HEAD -- '*.py'
Đây chính là bước Detect nối vào Verify: thay đổi ở đâu, kiểm ở đó.
Khung tư duy: thang mức độ drift
- Critical — tham số/return sai (người dùng làm sai theo docs). Chặn merge.
- Major — mô tả hành vi lỗi thời. Cảnh báo, nên sửa.
- Minor — ví dụ cũ, câu chữ. Ghi nhận, không chặn.
Định dạng báo cáo drift
Để bước Deliver (Bài 7) dùng lại được, hãy chuẩn hóa báo cáo thành JSON có cấu trúc, mỗi phát hiện kèm bằng chứng và gợi ý sửa:
{
"file": "user.py",
"symbol": "fetch_user",
"severity": "critical",
"type": "missing_param",
"detail": "Tham so 'timeout' co trong chu ky nhung thieu trong docstring",
"suggestion": "Them: timeout (int): Thoi gian cho toi da (giay). Mac dinh 30."
}
Có suggestion sẵn giúp reviewer sửa bằng một click, và cho phép Fix mode (Bài 7) áp dụng tự động.
Bắt LLM-judge nêu bằng chứng để giảm false positive
LLM-judge đôi khi báo drift không có thật. Cách hạ false positive: yêu cầu judge trích dòng cụ thể trong code và trong docstring mà nó cho là mâu thuẫn, và trả về OK khi không chắc thay vì đoán. Nếu judge không chỉ được bằng chứng rõ ràng, mặc định coi là không drift. Nguyên tắc: thà bỏ sót một drift nhỏ còn hơn làm phiền reviewer bằng cảnh báo sai, vì cảnh báo sai lặp lại khiến team mất niềm tin và tắt kiểm tra.
Kiểm tra drift cho README
Drift không chỉ ở docstring. Với README, so sánh có luật:
- Bảng biến môi trường vs
.env.example— thiếu/thừa biến nào? - Lệnh cài đặt vs
pyproject.toml/package.json— tên package, version còn đúng? - Danh sách lệnh CLI trong README vs entry point thật.
Sai lầm thường gặp
- Dùng LLM cho mọi kiểm tra. Đắt và không ổn định. Luật cứng bắt được đa số drift cấu trúc — dùng nó trước.
- Quét toàn repo mỗi lần chạy. Chậm, tốn tiền. Dựa vào git diff.
- Không phân mức nghiêm trọng. Nếu mọi drift đều fail CI, team sẽ tắt kiểm tra. Chỉ Critical mới chặn.
- Judge LLM không nêu bằng chứng. Yêu cầu nó chỉ rõ dòng nào sai để người review nhanh, tránh false positive.
- Bỏ qua README/env drift. Drift ở tầng README gây hại onboarding nặng — đừng chỉ kiểm docstring.