Nhiệt Thành

Mẫu AGENTS.md: luật làm việc cho AI trong một dự án nội dung

Đây là file luật mà mọi AI phải đọc trước khi sửa bất cứ thứ gì trong dự án của bạn. Mẫu có 10 mục và một bảng giải nghĩa từ, viết để người không lập trình đọc được: bạn ra luật, AI làm theo.

Trong bộ Nhiệt Thành OS bản 0.1.2, mẫu này vào dự án thành AGENTS.md. Mẫu dài 72 dòng, xem nguyên văn ở cuối trang.

Dùng khi nào

  • Bạn bắt đầu để AI làm việc trong một thư mục dự án và chưa có file luật nào.
  • Bạn dùng hơn một phiên AI cùng lúc và cần chốt phiên nào được giao việc, phiên nào chỉ được làm.
  • Bạn đã có file luật nhưng nó chỉ nói về viết mã, chưa nói về đăng, gửi, xoá và mật khẩu.

Cách điền

  • Đặt file ở thư mục gốc của dự án với tên AGENTS.md.
  • Mục 6 (kênh được máy tự đăng) để nguyên "không kênh nào" cho tới khi bạn thật sự muốn bật. Bật kênh nào thì ghi nguyên văn câu bạn đồng ý.
  • Mục 7 phải ghi rõ một phiên điều phối duy nhất. Để trống mục này là để ngỏ chuyện hai phiên cùng giao việc.
  • Mục 5 và mục 10 có chỗ chờ con số của riêng bạn (khung giờ, số phút, số giờ chạy ổn). Dự án chưa có gì chạy theo lịch thì ghi "chưa áp dụng".
  • Mục 8 dành cho AI viết mã. Bạn không cần hiểu hết; giữ nguyên là được.
  • Chỗ có «…» là chỗ phải điền. Còn «…» nghĩa là chưa xong.

Đi cùng với

Nguyên văn mẫu

Mọi tên trong ví dụ ("Kênh A") là tên giả.

# Luật làm việc cho mọi AI trong dự án «TÊN DỰ ÁN»

File này nằm ở thư mục gốc của dự án với tên `AGENTS.md`. AI nào mở thư mục cũng phải đọc nó trước khi sửa bất cứ thứ gì. Chỗ có «…» là chỗ còn chờ bạn trả lời; skill khởi tạo sẽ hỏi và điền giúp.

Bạn không cần biết lập trình để đọc file này. Luật viết cho AI làm theo, còn bạn là người ra luật và kiểm xem AI có làm đúng không.

## Vài từ dùng trong file này
| Từ | Nghĩa |
|---|---|
| Chủ dự án | Bạn. Người quyết mục tiêu và duyệt những việc không rút lại được. |
| Điều phối | Một phiên trò chuyện với AI được bạn chọn làm "quản lý": lên kế hoạch, viết phiếu việc, kiểm kết quả. Mỗi lúc chỉ có một. |
| Thợ | AI (hoặc người) nhận phiếu và làm việc trong phiếu. |
| Phiếu việc | Một file ngắn ghi rõ: làm gì, sửa ở đâu, thế nào là xong, cấm đụng gì. Tên file bắt đầu bằng `BRIEF-` và một con số. |
| Báo cáo | File thợ viết sau khi làm xong, tên bắt đầu bằng `REPORT-` và cùng con số với phiếu. |
| Nghiệm thu | Điều phối đối chiếu báo cáo với từng điều kiện "thế nào là xong" trong phiếu rồi ghi ĐẠT hay CHƯA ĐẠT. |
| Sao lưu | Chép một bản của file trước khi sửa, để hỏng thì lấy lại được. |
| Chạy thử | Cho công cụ chạy ở chế độ chỉ in ra màn hình, không ghi và không gửi gì thật. Trong lệnh, chế độ này là chữ `--dry`. |
| File bí mật `.env` | Nơi duy nhất được cất mật khẩu và khoá truy cập dịch vụ. Không bao giờ chép nội dung file này đi nơi khác. |

## 1. Ai làm gì
- **Chủ dự án («tên»):** chốt mục tiêu; duyệt mọi việc không rút lại được (đăng bài, gửi tin, xoá dữ liệu, trả tiền).
- **Điều phối:** một phiên AI duy nhất, ghi rõ ở mục 7. Lập kế hoạch, viết phiếu việc, nghiệm thu, cập nhật tài liệu.
- **Thợ:** nhận phiếu, làm đúng phiếu, chạy thử, viết báo cáo. Không tự làm thêm việc ngoài phiếu.

## 2. Một việc đi qua những bước nào
1. Điều phối viết phiếu việc vào `ops/briefs/`: mục tiêu, phạm vi, thế nào là xong, điều cấm, giờ được làm. Khuôn có sẵn ở `ops/mau/BRIEF.mau.md`.
2. Thợ sao lưu file sắp sửa (đặt tên `<tên file>.bak-<số phiếu>-<ngày>`), làm đúng phạm vi, chạy thử, rồi viết báo cáo vào `ops/reports/` theo khuôn `ops/mau/REPORT.mau.md`.
3. Điều phối nghiệm thu: đối chiếu từng điều kiện với kết quả thật, ghi ĐẠT, ĐẠT MỘT PHẦN hoặc CHƯA ĐẠT vào cuối báo cáo.
4. Việc đạt thì lưu lại thành một mốc trong lịch sử dự án (nếu dự án dùng git: một phiếu một lần lưu, ghi `BRIEF-xxx: tóm tắt`).

Việc nhỏ bạn giao thẳng trong lúc trò chuyện không cần phiếu, nhưng vẫn phải ghi một dòng vào nhật ký thay đổi `ops/CHANGELOG.md`.

## 3. Điều cấm
- Không đăng, gửi, xoá bất cứ thứ gì ra bên ngoài khi chủ dự án chưa đồng ý rõ ràng trong cuộc trò chuyện. Ngoại lệ duy nhất: các kênh đã ghi ở mục 6.
- Không viết mật khẩu hay khoá truy cập vào bất kỳ file nào ngoài `.env`. Không yêu cầu chủ dự án dán mật khẩu vào cuộc trò chuyện.
- Công cụ nào có tác dụng thật (đăng, gửi, ghi dữ liệu) thì lần đầu chỉ chạy ở chế độ chạy thử `--dry`. Công cụ không có chế độ chạy thử thì đọc mã của nó trước, không bấm thử.
- Không sửa file mà một phiếu khác đang làm dở.
- File làm tạm, dùng một lần thì đặt trong thư mục `scratch/`.
- Không bịa nguồn. Số liệu, câu trích, tên người trong bài phải lấy từ nguồn đã tải về và chỉ ra được.
- «điều cấm riêng của bạn»

## 4. Báo cáo chỉ ghi điều đã thấy
Ghi kết quả đúng như máy in ra. Không ghi "sẽ đạt", "chắc là được" cho lượt chưa chạy. Cuối mỗi báo cáo luôn có ba mục: đã bỏ qua gì, chưa kiểm được gì, rủi ro chủ dự án cần biết.

## 5. Giờ được sửa những thứ đang chạy thật
- Công cụ đang chạy theo lịch chỉ được sửa lúc nó nghỉ: «khung giờ».
- Sửa xong phải chạy thử xong trước lượt chạy thật kế tiếp ít nhất «N» phút.
- Dự án chưa có gì chạy theo lịch thì ghi "chưa áp dụng".

## 6. Kênh được máy tự đăng
Mặc định: **không kênh nào**. Mỗi kênh được bật ghi một dòng gồm: tên kênh, bật từ ngày nào, tối đa mấy bài một ngày, và nguyên văn câu chủ dự án đồng ý.

## 7. Chỉ một điều phối
- Điều phối chính: «phiên nào». Chỉ phiên này được viết phiếu mới, nghiệm thu và đổi trạng thái phiếu.
- Phiên AI khác chỉ làm việc được giao thẳng. Thấy việc cần điều phối xử lý thì ghi một dòng vào hộp việc `ops/inbox_dieu_phoi.md`, không tự mở phiếu.
- Số phiếu mới lấy bằng công cụ `cong-cu/so-phieu/so-phieu.js` ngay trước khi tạo phiếu. Không tự đếm bằng mắt: hai phiên cùng đếm sẽ ra trùng số.
- Một phiếu đi qua các trạng thái: Mở → Đang làm (ai, giờ nào) → Chờ nghiệm thu → Đã nghiệm thu (kết quả). Tạm ngưng thì ghi Tạm dừng và lý do.

## 8. Luật viết mã (dành cho AI viết mã; bạn không cần hiểu hết)
- Đọc phiếu và đoạn mã sắp sửa trước khi viết; liệt kê mọi nơi đang dùng đoạn đó.
- Dừng ở bậc đầu tiên làm được việc: có cần tồn tại không → dự án đã có chưa → thư viện chuẩn → thư viện đã cài → một dòng → mã tối thiểu.
- Lỗi sửa ở gốc một lần, không vá từng nơi dùng.
- Phần xử lý mới không đơn giản thì kèm một bài kiểm tự động nhỏ.
- Làm tắt có giới hạn thì ghi chú ngay tại chỗ: `// shortcut: <giới hạn>, <khi nào nâng cấp>`.
- Không bao giờ cắt bớt: kiểm dữ liệu vào từ bên ngoài, xử lý lỗi để không mất dữ liệu, bảo mật, các cổng chất lượng.
- Công cụ mới nào cũng phải hiểu hai chữ `--help` (in hướng dẫn rồi dừng) và `--dry` (chạy thử).

## 9. Tự hẹn giờ kiểm lại
Việc nào có kết quả đến sau (bài hẹn giờ đăng, lượt chạy ban đêm) thì điều phối tự hẹn lúc quay lại xem, và ghi kết quả thật vào báo cáo của việc đó.

## 10. Cách nghĩ chung
Việc tay lặp đi lặp lại thì biến thành công cụ. AI chỉ giữ phần cần suy nghĩ. Mỗi công cụ chạy ổn «48 giờ» rồi mới làm bản kế tiếp.

Dùng mẫu này thế nào

Bạn chép mẫu về và tự điền, hoặc tải cả bộ: khi đó AI hỏi bạn từng câu rồi điền giúp. Tải Nhiệt Thành OS 0.1.2.

Mẫu này là một phần của Nhiệt Thành OS. Bạn được dùng và sửa cho việc nội dung của chính bạn. Không đăng lại ở nơi khác, không bán. Toàn văn giấy phép ở file LICENSE trong tệp tải về.