- Chọn người đọc trước: nói rõ README dành cho ai và việc đầu tiên họ cần làm xong.
- Docstring ghi hợp đồng: mục đích, tham số, giá trị trả về, ngoại lệ và tác dụng phụ, không kể lại từng dòng code.
- Lệnh phải có thật: mỗi lệnh trong README phải có trong tệp cấu hình của dự án và được chạy lại trên máy sạch.
Bắt đầu từ một ví dụ cụ thể
Ví dụ xuyên suốt bài là một README cũ ghi lệnh chạy app start, trong khi script thật trong tệp cấu hình của dự án là npm run dev. AI chỉ đọc README cũ sẽ chép lại lỗi đó bằng câu văn trôi chảy hơn. Vì vậy các prompt bên dưới bắt AI chỉ ra nguồn trong repo cho từng lệnh, từng tham số và từng khẳng định trong tài liệu.
Chọn người đọc và nhiệm vụ
README cho người cài thư viện khác tài liệu cho người đóng góp. Hãy nêu họ biết gì, cần làm gì trong năm phút đầu và phần nào không thuộc trang này. AI không thể tự chọn cấu trúc đúng nếu chỉ nhận cả repo và câu “viết README”.
Docstring mô tả hợp đồng
Docstring nên nói mục đích, tham số, kết quả, ngoại lệ và lưu ý không hiển nhiên. Không cần lặp tên biến hay giải thích từng dòng. Với hàm công khai, ví dụ ngắn có giá trị. Hãy chọn chuẩn của ngôn ngữ và dự án, rồi yêu cầu giữ nhất quán.
README phải bám tệp thật
Cung cấp manifest, lệnh, biến môi trường mẫu, entry point và cấu trúc chính. Yêu cầu AI trích nguồn cho từng lệnh từ tệp dự án. Nếu không tìm thấy, nó phải đánh dấu chưa rõ, không bịa npm start hoặc tên biến cấu hình nghe hợp lý.
Chạy lại mọi ví dụ
Một code block trong tài liệu là lời hứa. Chạy từ môi trường sạch, kiểm output, đường dẫn và phiên bản. Không đưa khóa thật; dùng .env.example và giá trị giả. Nếu lệnh cần dịch vụ ngoài, nói điều kiện và cách nhận lỗi thay vì giả định luôn thành công.
Ghi giới hạn và xử lý lỗi
Người mới cần biết trường hợp không hỗ trợ, lỗi phổ biến và nơi tìm thêm. Yêu cầu AI dựa trên issue, code và log đã cung cấp, không tạo FAQ tưởng tượng. Một phần “Troubleshooting” ngắn nhưng đúng tốt hơn danh sách dài không kiểm được.
Giữ tài liệu đồng bộ
Khi interface đổi, tài liệu phải nằm cùng diff hoặc có test tài liệu. Yêu cầu review tên hàm, tham số và lệnh giữa code với Markdown. Đừng để AI cập nhật câu chữ mà bỏ ví dụ cũ. Chủ sở hữu thay đổi phải đọc bản render, không chỉ diff thô.
Bốn prompt mẫu chép dùng ngay
Prompt 1: lập dàn ý README theo người đọc
Repo này dành cho [đối tượng] và mục tiêu đầu tiên của họ là [nhiệm vụ]. Dựa chỉ trên cây tệp và nội dung tôi cung cấp, hãy lập dàn ý README theo hành trình: hiểu dự án, yêu cầu, cài, cấu hình, chạy ví dụ, kiểm kết quả, lỗi thường gặp và đóng góp. Mỗi mục ghi tệp nguồn cần đọc. Chưa viết nội dung; không đoán lệnh không thấy trong repo.
Prompt 2: viết docstring từ hợp đồng
Viết docstring cho [hàm/lớp] theo chuẩn [PEP 257/Google style/JSDoc...]. Chỉ dùng hành vi thể hiện trong code và test. Nêu mục đích, tham số, kiểu, return, exception, tác dụng phụ và một ví dụ tối thiểu. Không kể lại từng dòng, không hứa hành vi chưa có. Sau docstring, liệt kê điểm nào cần người viết xác nhận. [dán code và test].
Prompt 3: viết phần cài và chạy đã kiểm
Từ các tệp cấu hình dưới đây, viết phần “Cài đặt và chạy lần đầu” cho [hệ điều hành/phạm vi]. Mỗi lệnh phải xuất hiện hoặc suy ra trực tiếp từ tệp được nêu; ghi điều kiện trước lệnh và kết quả quan sát được sau lệnh. Dùng secret giả, không đưa giá trị thật. Chỗ thiếu bằng chứng ghi
CẦN XÁC NHẬN, không tự điền. [dán manifest, compose, Makefile, env mẫu].
Prompt 4: kiểm chéo tài liệu với code
Đối chiếu README/docstring với code, test và cấu hình. Trả bảng: khẳng định trong tài liệu, nguồn trong repo, trạng thái đúng/sai/không chứng minh, và sửa tối thiểu. Tập trung tên lệnh, tham số, giá trị mặc định, biến môi trường, đường dẫn và output ví dụ. Chưa viết lại toàn bộ tài liệu. [dán tài liệu và các tệp liên quan].
Khi kết quả chưa đúng thì sửa prompt thế nào
Nếu tài liệu bịa lệnh, yêu cầu bảng ánh xạ lệnh sang tệp nguồn. Nếu quá dài, chốt một đối tượng và một nhiệm vụ đầu tiên. Nếu docstring lặp code, yêu cầu chỉ giữ hợp đồng và điều không hiển nhiên. Nếu ví dụ không chạy, đưa lỗi nguyên văn và yêu cầu sửa đúng block. Nếu thiếu thông tin, dùng nhãn cần xác nhận thay vì để AI lấp chỗ trống.
Bài thực hành
Chọn một repo học tập nhỏ. Tự xác định người đọc rồi chạy Prompt 1. Viết phần cài bằng Prompt 3, mở môi trường sạch và chạy từng lệnh. Dùng Prompt 4 để bắt tên biến hoặc đường dẫn sai. Chỉ giữ câu mà bạn truy được về code hoặc phép chạy.
Ca mẫu: kiểm Quick start trên môi trường sạch
Một README nói chạy app start, trong khi script thật trong cấu hình là npm run dev và cần tệp .env.example. AI chỉ nhìn README cũ rất dễ viết lại lỗi đó trôi chảy hơn. Hãy cung cấp manifest, entry point, phiên bản runtime và workflow CI. Yêu cầu nó lập bảng cho từng lệnh: xuất hiện ở tệp nào, chạy tại thư mục nào, cần biến gì và dấu hiệu thành công là gì. Tự chạy các lệnh trên bản sao sạch hoặc container phù hợp; không coi một câu trả lời của AI là phép kiểm. Ví dụ đầu ra nên ngắn, không chứa token, đường dẫn máy cá nhân hoặc dữ liệu thật. Docstring cũng phải bám chữ ký và hành vi: mô tả đơn vị, lỗi và tác dụng phụ mà người gọi cần biết, không kể lại từng dòng. Nếu một option chưa được code hỗ trợ, xóa khỏi tài liệu hoặc đánh dấu kế hoạch, đừng bịa cách dùng. Cuối cùng nhờ một người mới làm đúng Quick start mà không được nghe giải thích miệng. Câu hỏi họ phải hỏi chính là dữ liệu tốt để sửa tài liệu vòng sau.
Prompt thứ năm: tự kiểm bằng tình huống của bạn
Hãy kiểm README như người mới vừa clone kho mã trên máy sạch. Đọc cấu hình, entry point và lệnh CI tôi dán; lập hành trình từ cài đặt tới kết quả đầu tiên. Với mỗi lệnh, ghi nguồn trong repo chứng minh nó tồn tại, thư mục làm việc, biến môi trường và đầu ra quan sát được. Không sáng tác URL, badge hay option. Chỗ thiếu bằng chứng hãy chèn TODO kèm câu hỏi cho maintainer. Sau đó viết lại riêng Quick start ngắn nhất, giữ cảnh báo quan trọng và tách rõ lệnh đã kiểm khỏi ví dụ minh họa.
Câu hỏi thường gặp
Docstring Python nên ghi những gì?
Theo PEP 257, docstring của hàm tóm tắt hành vi và ghi tham số, giá trị trả về, tác dụng phụ, ngoại lệ có thể ném và giới hạn khi gọi, nếu có.
Nên viết docstring theo kiểu Google hay NumPy?
PEP 257 nói docstring cần ghi những gì nhưng không quy định cách trình bày từng mục. Kiểu Google (mục Args:, Returns:) và kiểu NumPy (mục Parameters, Returns) đều phổ biến; chọn kiểu dự án đang dùng và yêu cầu AI giữ đúng kiểu đó.
Làm sao biết README do AI viết còn đúng?
Chạy lại từng lệnh trên một bản clone sạch. Lệnh nào không thấy trong tệp cấu hình của dự án thì đánh dấu cần xác nhận thay vì giữ lại.
Học tiếp
- Prompt đặt tên biến và hàm rõ nghĩa, nhất quán
- Prompt review code theo checklist: đúng, dễ đọc, an toàn
- Prompt viết thông báo commit rõ thay đổi và lý do
Khóa AI – Introduction to Machine Learning: nền tảng Máy học từ thuật toán cơ bản đến Neural Networks và LLM, học bằng Python. Học thử buổi 1 miễn phí.


