Tài liệu tôi viết giờ không để người đọc — để máy chạy
Tôi vừa tìm ra cách đo chất lượng tài liệu chính xác nhất trần đời: đưa cho một con AI làm theo, rồi xem nó phá cái gì.
Nghe đùa, nhưng đó là chuyện thật vừa xảy ra trong hệ thống của tôi. Và nó thay đổi hẳn cách tôi nghĩ về việc viết tài liệu khi build sản phẩm một mình.
Docs-as-code — chuyện cũ của dân làm phần mềm
Trong giới phần mềm có một trường phái gọi là docs-as-code: đối xử với tài liệu y như code. Viết bằng Markdown thuần, sống trong Git cùng repo, sửa thì review như review code, có công cụ soát lỗi văn phong, có máy tự kiểm tra link gãy, build ra trang web tự động.
Ý tưởng hay. Nhưng thú thật, với người làm một mình như tôi, trường phái này từng nghe rất... xa xỉ. Không có team thì viết tài liệu cho ai đọc? Cho chính mình ba tháng sau à? Động lực đó yếu lắm. Tài liệu vì thế luôn là thứ bị khất: "ship xong rồi viết".
Rồi mọi thứ đổi, vì tài liệu của tôi có một người đọc mới.
Người đọc mới: không phải người
Tôi build con bot spa của mình bằng một hệ thống AI agent — không ngồi gõ từng câu lệnh cho AI nữa, mà thiết kế quy trình để nó tự chạy. Và đây là điều tôi nhận ra: mọi quy trình đó, thực chất, là những file Markdown.
Trong repo của tôi có một file đặc biệt: con AI đọc nó đầu mỗi phiên làm việc, như nhân viên mới đọc sổ tay công ty. Trong đó ghi dự án này là gì, dữ liệu nằm đâu, quy ước đặt tên thế nào — và quan trọng nhất là ranh giới: chỗ nào chỉ được đọc không được sửa, và một lằn ranh cứng: không bao giờ tự ý deploy lên hệ thống thật, phải chờ tôi duyệt.
Rồi các quy trình lặp lại — soạn bài blog, duyệt, build trang, đẩy lên server, kiểm tra bản live — tôi đóng gói mỗi quy trình thành một file Markdown mô tả từng bước. Agent mở file, chạy đúng từng bước. Tôi không phải nhớ, không phải gõ lại, không sót bước nào.
Tức là tài liệu không còn là thứ viết xong để đó. Nó là thứ máy thực thi theo. Docs-as-code, theo nghĩa đen nhất: tài liệu chính là code — chỉ khác là viết bằng tiếng Việt thay vì Python.
Cái giá của một dòng mơ hồ
Nghe êm tai quá đúng không? Giờ kể đoạn trả giá.
Hệ điều phối của tôi cho phép rải nhiều task cho nhiều "lính" AI chạy song song, mỗi con một góc làm việc riêng, xong thì nộp bản vá về gộp lại. Tài liệu của tôi mô tả cách rải task — nhưng có một điều nó không nói rõ: khi các task phụ thuộc nhau thì sao?
Con orchestrator làm đúng những gì tài liệu viết: rải song song hết. Kết quả: task sau cần code của task trước, nhưng vì chạy song song từ nền code cũ, nó không hề thấy phần vừa làm xong — bản vá nộp về lệch hết. Cả loạt bốn task, hỏng cả bốn, không gộp được dòng nào. Một buổi chạy tự động đổ sông.
Điều đáng nói: con AI không làm sai. Nó làm đúng cái tài liệu sai. Lỗi là của người viết — là tôi.
Cách sửa cũng không phải sửa code. Là sửa tài liệu: tôi ghi thẳng vào đó một luật mới — task phụ thuộc nhau thì phải chạy tuần tự, cấm rải song song. Từ đó về sau, mọi phiên chạy đều né đúng cái hố đó. Bài học không nằm trong đầu tôi nữa — nó nằm trong file, và mọi phiên AI sau này tự động thừa hưởng nó.
Đó là lúc tôi vỡ ra: chất lượng tài liệu giờ đo được bằng kết quả thực thi. Viết rõ thì máy chạy đúng. Viết mơ hồ thì máy hỏng — ngay lập tức, đo đếm được. Không còn chuyện "tài liệu tạm ổn" theo cảm tính.
Spec cũng là file, không phải tin nhắn chat
Bước mới nhất tôi vừa làm hôm nay: một file duy nhất làm hộp spec. Muốn hệ thống làm gì, tôi viết thành một khối Markdown: muốn gì, có giao diện không, thế nào là xong. Mỗi spec có vòng đời trạng thái: nháp → chốt → xong.
Khi tôi đánh dấu chốt, pipeline tự chạy: spec có giao diện thì agent dựng mockup trước cho tôi duyệt cái nhìn, rồi mới code; code xong tự chạy test trong môi trường cô lập. Cả chuỗi đó tôi chỉ phải bấm ở hai chỗ — chốt spec và chốt mockup. Riêng deploy lên hệ thống thật vẫn là lằn ranh cứng chờ tôi.
Trước kia, "spec" của tôi là những tin nhắn chat với AI — nói xong là trôi, mai muốn làm tiếp phải kể lại từ đầu. Giờ spec là file trong Git: có trạng thái, có lịch sử, không bay hơi. Khác biệt nghe nhỏ, nhưng nó là khác biệt giữa ra lệnh miệng và vận hành có sổ sách.
Nếu bạn muốn bắt đầu
Không cần dựng cả hệ thống như tôi. Ba bước nhỏ thôi:
Một — tạo một file mô tả dự án cho AI đọc đầu phiên: dự án là gì, cấu trúc ra sao, và vài ranh giới "cấm làm". Riêng file này đã nâng chất lượng mọi phiên làm việc với AI lên rõ rệt.
Hai — việc gì bạn làm lặp lại lần thứ ba, viết thành checklist Markdown và để AI chạy theo. Mỗi lần nó vấp, sửa checklist chứ đừng chỉ sửa tay — để bài học ở lại trong file.
Ba — ngừng coi yêu cầu là tin nhắn chat. Coi spec là file có trạng thái: nháp, chốt, xong. Chat thì trôi; file thì tích luỹ.
Người làm một mình không có đồng nghiệp để truyền miệng quy trình. Nhưng từ giờ điều đó không còn là điểm yếu: bạn viết quy trình ra một lần, và có một "đồng nghiệp" đọc kỹ hơn bất kỳ con người nào — làm đúng từng chữ. Việc của bạn là viết những chữ đáng để làm theo.
👉 Muốn tự tay build con bot AI đầu tiên — và tập luôn thói quen viết quy trình ra file để AI chạy thay mình, thay vì gõ đi gõ lại từng câu lệnh? Bắt đầu với mini-course miễn phí: Bot AI đầu tiên của bạn — làm xong trong một buổi tối, và bạn sẽ có sản phẩm thật đầu tiên để bắt đầu vận hành như một người có cả team.