Bài 8 — Vận hành thực tế: đo lường, xử lý ngoại lệ và mở rộng

Agent đã chạy trong CI. Bài cuối bàn chuyện vận hành lâu dài: làm sao biết nó thật sự giúp ích, xử lý các tình huống khó, và mở rộng ra nhiều repo/ngôn ngữ mà không mất kiểm soát.

Đo lường: agent có đang giúp không?

Đừng đo bằng cảm tính. Bốn chỉ số cốt lõi:

• Doc coverage — % hàm/module public có docstring hợp lệ. Mục tiêu: tăng dần.
• Drift rate — số drift phát hiện mỗi tuần. Mục tiêu: giảm dần và bắt sớm.
• Time-to-fix — từ lúc phát hiện drift đến lúc sửa. Ngắn = quy trình tốt.
• Tỷ lệ chấp nhận — % gợi ý của agent được merge. Thấp = chất lượng gợi ý kém, cần chỉnh prompt.

metrics = {
    "doc_coverage": documented / total_public,
    "drift_open": count_open_drift(),
    "suggestion_accept_rate": accepted / suggested,
}

Đưa các số này lên dashboard hoặc comment tổng hợp hàng tuần.

Xử lý ngoại lệ thường gặp

• File sinh tự động (generated code, migrations) — đừng bắt agent viết docs. Dùng ignore-list.
• Code legacy khổng lồ — đừng ép 100% coverage ngay. Đặt "ratchet": chỉ yêu cầu docs cho code mới/đổi, không đụng phần cũ.
• LLM sập/timeout — agent phải fail-safe: khi không gọi được model, chỉ chạy kiểm deterministic, không fail toàn bộ CI vì lỗi hạ tầng.
• False positive từ judge — cho phép người đánh dấu "đã xem, không phải drift" để agent học và không báo lại.

Khung tư duy "ratchet" (bánh cóc)

Nguyên tắc mở rộng lên codebase lớn: không bao giờ để tệ đi, cải thiện dần.

• Đặt baseline coverage hiện tại (ví dụ 40%).
• CI chỉ chặn nếu coverage giảm dưới baseline, hoặc code mới thiếu docs.
• Mỗi PR nâng baseline một chút.
• Không đòi cả team dừng lại viết docs cho 5.000 hàm cũ — điều đó không bao giờ xảy ra.

Ratchet biến việc cải thiện docs thành liên tục và không đau.

Mở rộng đa ngôn ngữ / đa repo

• Tách phần language-specific (parser AST) khỏi phần chung (prompt, judge, delivery). Thêm ngôn ngữ = thêm một parser.
• Dùng tree-sitter để hỗ trợ nhiều ngôn ngữ với một giao diện.
• Đóng gói agent thành GitHub Action/CLI tái dùng để cắm vào nhiều repo.
• Chuẩn hóa cấu hình bằng một file docagent.yml mỗi repo (style, ignore, ngưỡng).

Checklist "sẵn sàng vận hành"

• [ ] Có ignore-list cho file sinh tự động.
• [ ] Fail-safe khi LLM lỗi (fallback deterministic).
• [ ] Ngưỡng drift phân cấp Critical/Major/Minor rõ ràng.
• [ ] Cơ chế đánh dấu false positive.
• [ ] Chiến lược ratchet cho legacy code.
• [ ] Dashboard/metric theo dõi coverage & accept-rate.
• [ ] Cấu hình per-repo bằng file rõ ràng.
• [ ] Kiểm soát chi phí token (cache + ngân sách).

Lộ trình 90 ngày triển khai vào một team thật

• Tuần 1-2 (Check-only, một repo): bật agent ở chế độ chỉ báo cáo, không chặn merge. Thu thập số liệu drift baseline và lắng nghe phản hồi.
• Tuần 3-4 (Bật chặn Critical): chỉ Critical mới fail CI. Cung cấp nhãn skip-doc-check cho ngoại lệ.
• Tháng 2 (Fix mode có nhãn): cho phép agent tự vá docs khi có nhãn doc-fix, người review commit.
• Tháng 3 (Ratchet + mở rộng): đặt baseline coverage, nâng dần; nhân bản agent sang repo/ngôn ngữ thứ hai qua Action tái dùng.

Triển khai từ tốn như vậy giúp team làm quen và tin tưởng agent trước khi trao cho nó quyền lớn hơn.

Khép lại vòng Detect–Generate–Verify–Deliver

Nhìn lại toàn khóa: Bài 3 dạy Detect/đọc code, Bài 4-5 dạy Generate docstring và README, Bài 6 dạy Verify drift, Bài 7 dạy Deliver qua CI/PR, và Bài 8 khép bằng vận hành. Bạn giờ có một Documentation Agent hoàn chỉnh, chạy thật, tự bảo trì docs cho dự án. Bước tiếp theo tùy bạn: mở rộng sang sinh changelog từ commit, tài liệu kiến trúc từ sơ đồ phụ thuộc, hay tích hợp vào cổng tài liệu nội bộ — nhưng khung tư duy bốn bước và nguyên tắc 'agent tạo nháp, người quyết định' vẫn giữ nguyên.

Sai lầm thường gặp

• Ép 100% coverage ngay trên codebase lớn. Team phản kháng, dự án bỏ. Dùng ratchet.
• Không đo gì cả. Không biết agent giúp hay chỉ gây ồn. Theo dõi coverage + accept-rate.
• Để CI fail khi LLM sập. Lỗi hạ tầng chặn merge làm cả team ghét agent. Fail-safe về deterministic.
• Không có đường thoát cho false positive. Reviewer mất niềm tin. Cho đánh dấu "không phải drift".
• Bó cứng vào một ngôn ngữ. Khó mở rộng. Tách parser khỏi lõi ngay từ đầu.
• Quên rằng agent tạo bản nháp, người quyết định. Ý đồ thiết kế và "tại sao" vẫn cần con người — agent lo phần cơ học, lặp lại, dễ drift.