Bài 1 — Vì sao cần Documentation Agent và bài toán "doc drift"

Tài liệu (documentation) là thứ mọi team đều biết là quan trọng nhưng luôn bị bỏ bê. Lý do đơn giản: viết docs tốn thời gian, và khi code thay đổi, docs không được cập nhật theo. Kết quả là doc drift — tài liệu ngày càng lệch khỏi thực tế của code, đến mức tệ hơn cả không có docs vì nó đánh lừa người đọc.

Một Documentation Agent là một tác nhân AI được lập trình để: đọc code, sinh ra tài liệu (docstring, README, API reference), phát hiện khi docs lỗi thời, và tự đề xuất bản cập nhật. Khóa học này dạy bạn xây dựng agent đó và vận hành nó trong dự án thật.

Doc drift trông như thế nào

Ví dụ cụ thể: một hàm ban đầu nhận 2 tham số, docstring mô tả đúng. Sáu tháng sau lập trình viên thêm tham số thứ ba timeout, nhưng quên sửa docstring.

def fetch_user(user_id, retries=3, timeout=30):
    """Lay thong tin user.

    Args:
        user_id: ID cua user
        retries: So lan thu lai
    # THIEU mo ta timeout -> doc drift
    """

Người đọc docstring sẽ không biết timeout tồn tại. Đây là dạng drift phổ biến và nguy hiểm nhất: docs có vẻ đúng nên không ai nghi ngờ.

Ba tầng tài liệu agent sẽ chăm sóc

• Docstring / inline comment — mô tả sát code, đi cùng hàm/class.
• README / hướng dẫn — mô tả cách cài đặt, chạy, ví dụ dùng.
• API reference / kiến trúc — mô tả tổng thể module, luồng dữ liệu.

Agent tốt phải hiểu cả ba tầng dùng chung một "nguồn sự thật" là source code, và giữ chúng đồng bộ.

Khung tư duy: "Docs-as-Code"

Triết lý cốt lõi của khóa học là Docs-as-Code: đối xử với tài liệu như đối xử với code — lưu cùng repo, review qua pull request, kiểm tra tự động trong CI, và versioned. Documentation Agent chính là công cụ tự động hóa vòng đời đó.

Khung 4 bước để tư duy về bất kỳ agent tài liệu nào:

• Detect — phát hiện thay đổi trong code (commit, PR, diff).
• Generate — sinh/cập nhật nội dung docs tương ứng.
• Verify — kiểm tra docs khớp code (còn drift không?).
• Deliver — mở PR, comment, hoặc commit bản cập nhật cho người review.

Mọi bài sau sẽ lần lượt hiện thực hóa 4 bước này.

Các bước bắt đầu ngay hôm nay

• Chọn một repo thật của bạn (Python/JS/TS đều được) làm sân tập xuyên suốt khóa.
• Chạy thử git log --oneline -20 để xem lịch sử thay đổi — đây là nguồn tín hiệu "Detect".
• Mở 3 file bất kỳ, tự chấm điểm docs của chúng theo thang: Không có / Có nhưng lỗi thời / Chính xác.
• Ghi lại 3 ví dụ doc drift bạn tìm được — đây sẽ là test case để nghiệm thu agent ở cuối khóa.
• Cài sẵn Python 3.10+ và một API key của một LLM (OpenAI, Anthropic, hoặc model local) để chuẩn bị cho Bài 2.

Checklist "khi nào cần Documentation Agent"

• [ ] Codebase thay đổi nhanh, docs không theo kịp.
• [ ] Có nhiều người dùng lại API/thư viện của bạn.
• [ ] Onboarding thành viên mới mất nhiều thời gian vì docs không tin được.
• [ ] Bạn có CI/CD và muốn gắn kiểm tra docs vào đó.

Nếu bạn tick từ 2 ô trở lên, ROI của một Documentation Agent là rất cao.

Sai lầm thường gặp

• Kỳ vọng agent tự viết 100% docs không cần người duyệt. Agent tạo bản nháp chất lượng cao, nhưng người vẫn review — nhất là với quyết định thiết kế và ý đồ ("why").
• Chỉ sinh docs một lần rồi quên. Không có bước Verify/cập nhật thì bạn chỉ dời drift sang tương lai.
• Coi docstring là thứ duy nhất. README và kiến trúc drift cũng gây hại lớn khi onboard người mới.
• Không có nguồn sự thật rõ ràng. Nếu docs và code cùng bị sửa tay rời rạc, agent không biết dựa vào đâu. Luôn lấy source code làm gốc.

Kết bài: bạn đã có bức tranh vấn đề và khung Detect–Generate–Verify–Deliver. Bài 2 ta sẽ dựng môi trường và bộ khung agent tối thiểu.