Vấn đề
Nhân viên TTMI dùng một hệ thống ERP tự phát triển ở 50 cửa hàng, và họ cần một cổng hướng dẫn giải thích cách làm các việc hằng ngày trong những module như nhân sự và vận hành. Nội dung hướng dẫn cũ nằm trong vài file nguồn rất lớn, sửa tay. Merge rất khó, còn người không phải kỹ sư thì gần như không review được.
Phần khó hơn nằm ở cách nội dung được viết ra. Muốn mô tả đúng một màn hình thì phải đọc code frontend và backend thật của ERP. Vì vậy bản nháp nào cũng mang theo chi tiết nội bộ như API path, tên module backend, tên branch, và những thứ đó tuyệt đối không được xuất hiện trên trang dành cho nhân viên. Thêm vào đó, phần lớn nội dung do AI coding agent soạn, và hướng dẫn do AI viết thường lệch khỏi UI thật: bịa ra màn hình, giữ nhãn nút cũ, ghi sai trường bắt buộc.
Tôi đặt ra ba mục tiêu. Nội dung sai không được ship. Chi tiết nội bộ không được ship. Và bản thân cổng hướng dẫn không bao giờ được trở thành runtime dependency của ERP hay một chỗ có thể rò rỉ dữ liệu.
Tôi đã làm gì
Content contract có kiểu, fail ngay lúc build
Tôi thiết kế mỗi module ERP thành một content package độc lập theo một contract có kiểu, cùng một registry trung tâm mà UI đọc vào. Registry validate từng package ngay khi build import nó. Package sai cấu trúc thì build dừng.
Cái giá là không có chuyện “xuống cấp nhẹ nhàng”. Tôi chấp nhận, vì một bài hướng dẫn sai mà không ai biết còn tệ hơn một lần deploy fail rõ ràng.
Markdown với parser chặt chẽ lúc build
Tôi thay các catalog sửa tay bằng file Markdown có frontmatter cấu trúc, đọc bởi một parser nhỏ, không phụ thuộc thư viện ngoài, chạy lúc build và ép đúng schema. Giờ người không phải kỹ sư cũng review được một bài viết như văn bản thường trong diff.
Đổi lại, cả catalog nằm trong bundle, không lazy loading. Với một catalog nội bộ có giới hạn, việc không phải parse lúc runtime và kiểm tra schema cứng là đáng.
Tách nội dung công khai và nội bộ, do build ép buộc
Mỗi bài có hai phần: hướng dẫn cho nhân viên, và một tài liệu kỹ thuật nội bộ mà AI agent dùng để bám vào thực tế. Tài liệu nội bộ không bao giờ được bundle. Một build guard từ chối mọi hướng dẫn công khai chứa dấu hiệu kỹ thuật nội bộ. Các integrity assertion chặn việc bài viết biến mất mà không ai hay, và chặn bản nháp lên live.
Người viết sẽ gặp build fail vì những câu chữ làm lộ thông tin. Sự vướng víu đó là có chủ đích.
Biên bản kiểm chứng cho nội dung do AI tạo
Tôi coi output của AI như một dependency không đáng tin. Với mỗi đợt tính năng, biên bản ghi lại đúng phiên bản app và backend, khôi phục một snapshot database cục bộ có giới hạn phạm vi, rồi chạy lại workflow thật qua UI thật bằng các tài khoản vai trò giả lập. Sau đó nó kiểm tra trạng thái đã lưu qua HTTP thay vì tin vào màn hình, kiểm tra từng file ảnh, và kết thúc bằng một danh sách “chưa kiểm chứng” rõ ràng. Một chuẩn chụp màn hình bằng văn bản cấm dùng UI do AI vẽ lại.
Cách này chậm hơn đọc diff, và công khai là chưa đầy đủ. Ghi rõ những chỗ còn thiếu rẻ hơn là nói quá độ phủ.
Không network, không backend
Cổng không gọi API, không có CMS, analytics hay đăng nhập. Nội dung và search index được bundle lúc build, trạng thái tìm kiếm nằm trên URL. Tìm kiếm bỏ qua dấu tiếng Việt nhờ Unicode decomposition cộng một fallback riêng cho chữ cái duy nhất mà decomposition không tách được, nên nhân viên gõ không dấu vẫn khớp được nội dung trong từng bước.
Đổi lại là không có nội dung live và không có fuzzy search. Với một catalog nội bộ chỉ đọc, như vậy là chấp nhận được.
Kết quả
Cổng đã được deploy và dùng trong toàn công ty như một sản phẩm nội bộ. Module ERP thứ hai được ship dưới dạng một content package bổ sung; thay đổi duy nhất trong code dùng chung là một dòng trong registry. Các catalog sửa tay đã được thay hoàn toàn bằng pipeline Markdown có validate, và tài liệu kỹ thuật nội bộ nằm ngoài bundle ngay từ thiết kế.
Quy trình kiểm chứng cũng bắt được lỗi của chính nó: một lần chạy lại phát hiện một kết luận sai trước đó và sửa lại trước khi xuất bản. Tôi không đưa ra số liệu về mức sử dụng, tỉ lệ lỗi hay thời gian tiết kiệm, vì chưa đo.
Nếu làm lại
Dự án chưa có test tự động hay CI riêng. Các build gate mang chính sách, nhưng bản thân các gate chưa được test, nên việc đầu tiên tôi sẽ làm là viết test cho parser và leak guard. Tôi cũng sẽ đặt size budget cho bundle sớm, trước khi catalog lớn tới mức lựa chọn không lazy loading trở nên đắt.