Biến code trong tài liệu thành mẫu chạy được để giảm lỗi docs

LangChain mô tả cách tách code inline khỏi tài liệu thành mẫu chạy được, trích snippet trở lại docs và dùng Deep Agents CLI hỗ trợ chuyển đổi. Đây là một gợi ý để QA đưa ví dụ tài liệu vào quy trình kiểm tra hồi quy.

Một code block trong docs có thể trông hoàn toàn hợp lệ nhưng đã không còn chạy được vì dependency, SDK hoặc API thay đổi. Lỗi này có thể chỉ lộ ra khi ai đó sao chép và chạy mẫu.

LangChain mô tả một cách xử lý: tách code inline trong tài liệu thành file ví dụ độc lập, làm các file này có thể chạy, rồi trích phần cần hiển thị trở lại docs. Với QA, đây là một tư duy đáng chú ý: coi code sample là artefact cần kiểm tra hồi quy, không chỉ là nội dung Markdown.

“Docs tự kiểm tra” nghĩa là gì?

Code inline trong Markdown hoặc MDX thường chỉ là nội dung được định dạng như mã nguồn. Nếu không được chạy hoặc kiểm tra, nó có thể lệch khỏi sản phẩm khi API hay dependency thay đổi.

Theo LangChain, quy trình thủ công để biến code sample thành nội dung có thể kiểm tra gồm:

Tách code inline ra thành file độc lập. Bổ sung setup và teardown để ví dụ có thể chạy. Đánh dấu phần mã cần hiển thị trong tài liệu. Dùng công cụ trích xuất snippet đã đánh dấu. Chèn snippet được tạo vào docs. Chạy các ví dụ trong quy trình kiểm tra tự động.

Mục tiêu là phát hiện sớm khi ví dụ không còn thực thi được, thay vì để code trong tài liệu âm thầm lỗi thời.

Với tester, code sample từ đây có thể thuộc phạm vi regression: có đầu vào, trạng thái pass/fail và log để điều tra khi xảy ra lỗi.

LangChain dùng Deep Agents CLI để hỗ trợ chuyển đổi

LangChain cho biết họ dùng Deep Agents CLI, một agent dòng lệnh có thể sử dụng skills — các bộ chỉ dẫn tái sử dụng cho những tác vụ phù hợp.

Skill được đề cập nằm trong repository tài liệu tại:

text .agents/skills/docs-code-samples/SKILL.md

Theo mô tả trong bài viết, skill này phục vụ việc chuyển code sample trong file MDX sang các file code bên ngoài có thể chạy. Bluehawk trích xuất đoạn mã, còn Mintlify sử dụng các snippet đó trong docs.

Các bước được hướng dẫn cho agent gồm:

Đưa code vào src/code-samples/{product}, tổ chức theo khu vực sản phẩm. Thêm setup và teardown để mẫu trở thành ví dụ hoàn chỉnh. Lint code bằng các linter đã cấu hình. Đánh dấu snippet bằng :snippet-start: và :snippet-end:. Loại phần không cần hiển thị bằng :remove-start: và :remove-end:. Chạy code sample. Sinh snippet từ markup và đưa nội dung sinh ra vào tài liệu.

Bài viết đưa ra ví dụ yêu cầu:

text migrate the inline code in streaming.mdx to testable code samples

Khi được dùng trong repository docs cùng skill phù hợp, agent có thể hỗ trợ tạo file, thêm marker, chạy các lệnh theo quy ước và cập nhật phần sử dụng snippet trong tài liệu.

Điều QA có thể học từ cách làm này

Giá trị chính không nhất thiết là để agent “viết test thay tester”. Điểm quan trọng hơn là chuẩn hóa một công việc dễ bị bỏ sót:

Tách ví dụ khỏi nội dung trình bày. Làm ví dụ đủ điều kiện để chạy. Xác định chính xác phần người đọc cần thấy. Liên kết phần hiển thị với mã nguồn có thể kiểm tra.

Agent có thể xử lý các bước mang tính cơ học nếu skill nêu rõ quy ước. QA vẫn cần review các câu hỏi quan trọng hơn: ví dụ có phản ánh đúng điều tài liệu hứa hẹn không, có phụ thuộc không ổn định không, và tiêu chí thành công có đủ ý nghĩa không.

Áp dụng cho repo nội bộ: bắt đầu từ sample rủi ro cao

Không nhất thiết phải chuyển toàn bộ docs trong một lần. Có thể ưu tiên các ví dụ:

Gọi SDK hoặc API thay đổi thường xuyên. Quickstart mà người dùng có xu hướng sao chép nguyên khối. Tích hợp dịch vụ bên thứ ba. Cấu hình cần biến môi trường hoặc xác thực. Luồng có nhiều bước setup mà code inline dễ bị thiếu ngữ cảnh.

Tester và developer có thể mô tả skill như một test procedure có thể review:

Đầu vào: file docs và các code block cần chuyển. Đầu ra: file mẫu có thể chạy, vùng snippet được đánh dấu và thay đổi docs tương ứng. Quy ước: cấu trúc thư mục, cách đặt tên, dependency, dữ liệu test và cách kiểm tra.

Trước khi cho agent sửa file, đội ngũ có thể yêu cầu agent lập kế hoạch: liệt kê code block cần chuyển, xác định dependency và biến môi trường, chỉ ra phần setup không nên hiện trong docs, đồng thời nêu các rủi ro như gọi mạng hoặc cấu hình chưa rõ.

Một sơ đồ CI tối giản

LangChain nêu rằng ngoài workflow agent, cần có GitHub Action chạy kiểm tra thường xuyên và tạo ticket khi test thất bại. Bài viết không cung cấp cấu hình Action hoặc câu lệnh cụ thể.

Dưới đây là sơ đồ đề xuất ở mức khái niệm cho một pipeline kiểm tra docs-code. Đội ngũ cần thay các placeholder bằng công cụ và lệnh hiện có của repo:

yaml jobs: verify-doc-samples: steps: checkout: source

name: Verify docs references run: <kiểm tra docs đang tham chiếu tới snippet đã sinh>

Việc sample chạy thành công chỉ là mức kiểm tra cơ bản. Với mỗi ví dụ quan trọng, đội ngũ vẫn cần assertion gắn với mục đích của tài liệu: ví dụ cần chứng minh một kết quả, trạng thái hoặc hành vi mà trang docs đang hướng dẫn, thay vì chỉ xác nhận chương trình không báo lỗi.

Các điểm cần review trước khi merge

Một pull request có pipeline xanh chưa chắc đã tạo ra ví dụ tốt. Khi review, hãy kiểm tra:

Độ đầy đủ: Sample có đủ phần cần thiết để chạy trong môi trường đã định nghĩa không? Độ trung thực: Snippet hiển thị có thực sự được trích từ file đang chạy không? Mục tiêu kiểm tra: Assertion có xác nhận đúng hành vi mà tài liệu mô tả không? Độ ổn định: Sample có phụ thuộc mạng, thời gian, quota hoặc dữ liệu biến động không? Marker: Setup có bị lộ trong docs, hoặc phần người dùng cần sao chép có bị loại bỏ không? Bí mật: Không đưa token, API key hoặc dữ liệu nhạy cảm vào sample, docs hay prompt gửi cho công cụ.

Checklist ngắn trước khi merge

[ ] Code block quan trọng có file mẫu tương ứng. [ ] Snippet trong docs được trích từ source, không sao chép thủ công. [ ] Lint, chạy sample và sinh snippet nằm trong quy trình kiểm tra phù hợp. [ ] Sample quan trọng có assertion phù hợp với mục đích của tài liệu. [ ] Đội ngũ đã đánh giá rủi ro flaky và không đưa credential thật vào ví dụ.

Tài liệu là một phần của trải nghiệm sản phẩm. Khi code trong docs được tổ chức để có thể chạy và kiểm tra, đội ngũ có thêm cơ hội phát hiện lỗi trước khi ví dụ lỗi thời đến tay người đọc.