Lưu trữ tài liệu cùng mã nguồn: Xu hướng tất yếu trong kỷ nguyên AI

Đã đến lúc chuyển tài liệu vào kho mã nguồn

Nét mực mờ còn hơn trí nhớ tốt nhất. – Ngạn ngữ Trung Quốc

Trí tuệ nhân tạo (AI) đang thay đổi cuộc chơi trong việc lưu trữ toàn bộ tài liệu trong kho mã nguồn của bạn: chưa bao giờ việc giữ chúng luôn cập nhật lại trở nên dễ dàng đến thế!

Từ lâu, việc đặt tài liệu sống cùng với mã nguồn đã mang lại nhiều lợi ích:

Quản lý phiên bản: Giống như mã nguồn, tài liệu cũng liên tục phát triển. Tại sao phải sử dụng một hệ thống quản lý phiên bản khác trong khi bạn đã có sẵn Git? Điều này đặc biệt hữu ích khi nhiều người cùng lúc thay đổi tài liệu và có khả năng xảy ra xung đột.

Gần gũi với mã nguồn: Các công cụ như rg hay grep sẽ trả về kết quả từ cả mã nguồn và tài liệu, giúp việc duy trì sự đồng bộ trở nên đơn giản hơn rất nhiều.

Quy trình phê duyệt chính thức: Theo tinh thần của phát triển hướng tài liệu (documentation-driven development), việc bắt đầu bằng cách đánh giá các cập nhật tài liệu giúp mọi người hiểu rõ hơn về sản phẩm/API cuối cùng. (Tuy nhiên, đối với việc cộng tác tích cực, các công cụ khác như Google Docs vẫn cung cấp trải nghiệm người dùng vượt trội).

Tự động tạo tài liệu: Khi sử dụng một hệ thống riêng để lưu trữ tài liệu (Google Docs, Confluence, Notion, v.v.), việc sao chép các API và mã ví dụ khá tốn công sức. Có nhiều công cụ (ví dụ: Sphinx's autodoc, jsdoc, javadoc, docusaurus) có thể tạo tài liệu API trực tiếp từ mã nguồn.

Kiểm thử: Các ví dụ mã nguồn tĩnh trong tài liệu là một khởi đầu tốt, nhưng sẽ còn tốt hơn nữa khi chúng được kiểm thử. Bạn có thể thực hiện điều này bằng cách tích hợp việc chạy các ví dụ mã trong tài liệu vào quy trình tích hợp liên tục (CI). Python's doctest là một ví dụ điển hình. Theo một cách nào đó, tài liệu chính là bản đặc tả (spec).

Chỉnh sửa hiệu quả: Bạn được hưởng lợi từ tất cả các công cụ trong trình soạn thảo văn bản của mình và có thể viết kịch bản để thực hiện các thay đổi hàng loạt.

Chúng ta sẽ dành nhiều thời gian hơn để viết tài liệu

Một quan sát ban đầu: các tác tử AI (AI agents) đã làm tăng đáng kể tỷ lệ các tệp Markdown trong các commit. Điều này thường là do mọi người kiểm tra quá trình triển khai của agent, một ý tưởng rất hay. Một lý do khác là bạn tiết kiệm được rất nhiều thời gian lặp lại của agent khi viết các tệp quy tắc (ví dụ: tệp .mdc) để định hướng hoạt động của chúng. Vì vậy, dù bạn có đồng ý với luận điểm này hay không, nó vẫn đang diễn ra.

Có thể nói rằng 80% nội dung trong các tệp quy tắc này có thể đã là tài liệu, hoặc có khả năng đã được ghi lại ở một nơi khác. Giống như mã nguồn nên được viết chủ yếu cho con người đọc, tất cả các tệp trong một kho mã nguồn cũng được viết chủ yếu để con người đánh giá (review). Điều này cũng áp dụng cho các tệp quy tắc được tạo ra để hướng dẫn agent. Các tệp quy tắc ngày càng giống với các hướng dẫn về phong cách (style guides) và các phương pháp hay nhất mà chúng ta chưa bao giờ bận tâm viết ra nhưng có lẽ nên hệ thống hóa lại.

Ranh giới giữa tệp Markdown chỉ dành cho AI và chỉ dành cho con người rất mờ nhạt, đến mức các tệp quy tắc có thể hoàn toàn biến mất và được thay thế bằng tài liệu.

Điều này cũng phù hợp với xu hướng các kỹ sư dịch chuyển trọng tâm sang giai đoạn đầu của quy trình (shift left). Các công cụ kỹ thuật đã có xu hướng trừu tượng hóa ngày càng cao, từ mã máy đến C, đến các ngôn ngữ động, đến SDK, và bây giờ là không cần viết mã mà chỉ tập trung vào đặc tả và hướng dẫn. Giống như chúng ta không đánh giá mã máy do trình biên dịch tạo ra, có thể sẽ có một ngày chúng ta không cần đánh giá mã do LLM tạo ra, miễn là nó tuân thủ các khuôn khổ, đặc tả và hướng dẫn (bảo mật sẽ là một mối quan tâm chính ở đây). Trong thế giới đó, chúng ta sẽ dành phần lớn năng lượng để đánh giá các đặc tả, khuôn khổ và hướng dẫn. Kết luận: những tài liệu đó cần được viết chủ yếu để con người đánh giá.

Tại sao AI làm cho việc chuyển tài liệu vào kho mã nguồn trở nên ý nghĩa hơn

Tác tử AI giải quyết vấn đề tài liệu lỗi thời. Một phản đối phổ biến đối với việc viết tài liệu là: "Tại sao phải bận tâm? Cứ đọc mã nguồn đi - mã nguồn luôn được cập nhật". Các tác tử AI giải quyết vấn đề này. Chúng loại bỏ công việc tốn sức để đảm bảo sự đồng bộ giữa mã nguồn và tài liệu (trong quá trình Pull Request, hoặc với các agent chuyên đánh giá để tìm kiếm sự không nhất quán trong tài liệu). Đây thực sự là một thay đổi mang tính cách mạng.

Tác tử AI hưởng lợi từ ngữ cảnh cấp cao. Việc chuyển tài liệu của bạn (bao gồm cả các đề xuất kiến trúc - RFC, đặc tả sản phẩm - PRD, v.v.) vào kho mã nguồn sẽ cung cấp thêm ngữ cảnh đó.

Các kế hoạch và phát hiện được ghi lại sẽ tiết kiệm token và thời gian lặp lại. Hãy tưởng tượng bạn đang nghiên cứu "cách tốt nhất để làm X" trong một codebase khổng lồ. Bạn sẽ tốn rất nhiều token để tìm câu trả lời. Việc ghi lại câu trả lời đó và lưu nó trong kho mã nguồn sẽ cho phép đồng nghiệp của bạn bỏ qua bước nghiên cứu đó sau này (và cập nhật nó với các bài học, phương pháp hay nhất, v.v.!). Điều này đặc biệt đúng với những thứ mà agent không thể suy ra từ mã nguồn, hoặc khó suy ra: điển hình là những vấn đề liên quan đến hạ tầng mà bạn học được khi triển khai mã nguồn lên môi trường production.

Giải đáp các phản biện thường gặp

Bạn có thể sử dụng các phương pháp khác để cấp quyền truy cập tài liệu cho agent. Nhưng những lập luận tôi đã đưa ra ở đầu bài viết vẫn còn nguyên giá trị, đặc biệt là phần về quản lý phiên bản. Hầu hết các hệ thống tài liệu không được thiết kế cho việc lặp lại nhanh với khả năng kiểm soát đồng thời mạnh mẽ.

Việc chờ đợi đánh giá mã nguồn cho tài liệu sẽ làm nản lòng việc cập nhật. (1) Điều gì sẽ xảy ra nếu không phải bạn là người viết những tài liệu đó? (2) Ai nói rằng mọi thay đổi nội dung trong kho mã nguồn đều cần phải qua đánh giá? (3) Khi chúng ta ngày càng dịch chuyển sang giai đoạn đầu, liệu việc thay đổi tài liệu hoặc kế hoạch triển khai có phải là điều quan trọng nhất cần đánh giá không?

Tác tử AI viết tài liệu dài dòng, phức tạp. Câu trả lời đầu tiên: hầu hết con người cũng vậy :). Giống như mã nguồn, bạn nên (1) đánh giá công việc của agent, (2) sửa chữa công việc của agent, và (3) tự viết tài liệu của riêng mình. Việc đưa nó vào hệ thống quản lý phiên bản giúp việc lặp lại trở nên DỄ DÀNG và an toàn hơn rất nhiều (nhờ có đánh giá và lịch sử thay đổi!).

Tôi có thực sự cần chuyển tất cả tài liệu của mình không? Tôi sẽ nói là có, tại thời điểm này. Không phải là những tài liệu tạm thời, mà là mọi thứ cung cấp ngữ cảnh hữu ích về codebase, bao gồm cả các RFC.

[Công cụ yêu thích của bạn] tốt hơn trong việc xử lý [bảng/sơ đồ/liên kết]. AI đang ngày càng trở nên xuất sắc trong việc tạo ra các sơ đồ Mermaid (được Github hỗ trợ), bảng biểu, v.v.

[Công cụ yêu thích của bạn] tốt hơn cho việc cộng tác giữa người với người. Đúng vậy, Google Docs vẫn tốt hơn nhiều cho việc cộng tác tích cực, vì vậy việc tiếp tục sử dụng nó cho trường hợp đó là hợp lý. Nhưng một khi tài liệu đã ở trạng thái tốt, tôi sẽ chuyển nó vào kho mã nguồn.

Những người không phải kỹ sư thường không có quyền truy cập kho mã nguồn. (1) Bạn có thể triển khai tài liệu của mình trên một trang web chỉ dành cho nội bộ. (2) Có một xu hướng rõ ràng là những người không phải kỹ sư cũng được cấp quyền truy cập mã nguồn (điều này đặt ra một số thách thức bảo mật thú vị).