Dari-docs: Tối ưu hóa tài liệu kỹ thuật để các tác nhân AI có thể tự triển khai mã nguồn

Trong kỷ nguyên lập trình được hỗ trợ mạnh mẽ bởi AI, việc viết tài liệu kỹ thuật (documentation) đang đối mặt với một sự thay đổi lớn về mục tiêu. Trước đây, tài liệu tốt được định nghĩa là tài liệu mà một lập trình viên con người có thể "hiểu sau một hồi suy ngẫm". Tuy nhiên, khi người đọc chính của chúng ta là các tác nhân AI như Claude Code hay Codex, sự mơ hồ trở thành rào cản cốt lõi khiến các mô hình ngôn ngữ thất bại trong việc triển khai mã.

Dari-docs là một dự án mới ra mắt nhằm giải quyết vấn đề này. Về bản chất, đây là một công cụ dòng lệnh (CLI) cho phép người dùng kiểm tra xem tài liệu của mình có đủ rõ ràng để các tác nhân AI có thể thực hiện các tác vụ thực tế hay không.

Thách thức khi viết tài liệu cho AI

Con người thường có khả năng bù đắp cho các thiếu sót trong tài liệu, chẳng hạn như thuật ngữ không nhất quán hoặc ngữ cảnh bị phân tán qua nhiều trang. Tuy nhiên, đối với các tác nhân AI, những thiếu sót này không chỉ gây lãng phí tài nguyên tính toán mà còn dẫn đến việc hoàn toàn không thể thực hiện nhiệm vụ.

Dari-docs chuyển đổi vấn đề chất lượng tài liệu từ cảm tính sang khách quan: "Liệu một tác nhân với khả năng thấp nhất có thể triển khai tính năng này một cách đáng tin cậy chỉ dựa trên tài liệu này không?".

Cơ chế hoạt động: Thử nghiệm song song

Dari-docs hoạt động bằng cách mô phỏng quy trình làm việc của một nhà phát triển. Người dùng có thể tải tài liệu lên thông qua trang web hoặc CLI và cung cấp một danh sách các nhiệm vụ cần hoàn thành (ví dụ: "Cài đặt SDK và thực hiện cuộc gọi API đầu tiên").

Hệ thống sẽ sau đó chạy song song nhiều tác nhân AI với các mức độ thông minh và chi phí khác nhau để cố gắng hoàn thành nhiệm vụ đó. Các tác nhân này sẽ thực hiện quy trình end-to-end: tìm kiếm thông tin trong tài liệu, làm theo hướng dẫn, chạy các lệnh, thử các ví dụ và thậm chí tự gỡ lỗi khi gặp lỗi.

Phát hiện lỗi và đề xuất sửa đổi tự động

Khi một tác nhân bị mắc kẹt, Dari-docs sẽ ghi nhận chính xác vị trí tài liệu gây ra sự hiểu lầm. Công cụ sẽ báo cáo các ngữ cảnh bị thiếu, các bước thiết lập không rõ ràng, hoặc những nơi tác nhân phải "đoán mò".

Điểm nổi bật là tính năng optimize. Thay vì chỉ báo lỗi, một tác nhân biên tập khác sẽ đề xuất các thay đổi cụ thể cho tài liệu dựa trên phản hồi đó. Người dùng có thể xem xét các bản sửa đổi này trong thư mục cục bộ trước khi áp dụng vào kho lưu trữ chính thức.

Xác minh trực tiếp với Live Verification

Dari-docs không chỉ dừng lại ở việc phân tích tĩnh. Công cụ cho phép bật tính năng xác minh trực tiếp (live verification) bằng cách cung cấp thông tin xác thực kiểm thử (test credentials). Điều này cho phép các tác nhân thực thi các workflow chống lại API thực tế, đảm bảo rằng tài liệu không chỉ lý thuyết đúng mà còn hoạt động được trong môi trường production.

Hiện tại, dự án hỗ trợ hai chế độ: Managed (sử dụng dịch vụ lưu trữ của dari.dev) và Self-managed (chạy trên tổ chức dari.dev của riêng bạn). Với sự gia tăng của các MCP server, SDK và API phức tạp, Dari-docs hứa hẹn将成为 một công cụ hữu ích để đảm bảo tài liệu kỹ thuật thực sự hữu ích cho cả con người và máy móc.