AGENTS.md: biến chuẩn làm việc thành trí nhớ bền

English title: AGENTS.md: Durable Project Instructions

Cập nhật: 29/06/2026. Đây là bài 3 trong chuỗi Codex Power 10 - 10 bài hướng dẫn dùng các năng lực mạnh của Codex theo cách có kiểm soát.

Bạn sẽ biết đưa gì vào AGENTS.md, đưa gì vào prompt ngắn, và cách tránh biến file hướng dẫn thành một bức tường chữ không ai còn đọc.

Bảng Nhớ Nhanh

Dùng bài này khi: bạn phải nhắc lại cùng một chuẩn làm việc qua nhiều phiên Codex.

Không dùng bài này khi: yêu cầu chỉ đúng một lần hoặc còn đang thử nghiệm chưa thành quy ước.

Xong bài khi: AGENTS.md có lệnh kiểm tra, vùng cấm, chuẩn phản hồi và gotcha đủ ngắn để đọc.

Ghi nhớ: Bài thực hành này không cố làm bạn nhớ hết tính năng. Nó giúp bạn dựng một vòng làm việc có mục tiêu, có biên và có bằng chứng.

Trước Khi Bắt Đầu

• Chọn repo có ít nhất một lệnh build/test rõ.
• Liệt kê ba phản hồi bạn thường phải sửa Codex.
• Tách quy tắc bền khỏi yêu cầu chỉ đúng cho task hiện tại.

Cẩn trọng: Nếu môi trường hoặc quyền đang mơ hồ, hãy dừng một nhịp để kiểm tra. Agent chạy nhanh trong bối cảnh sai sẽ tạo ra diff rất thuyết phục nhưng khó dùng.

Ý Tưởng Trong 3 Phút

Nếu mỗi phiên đều phải nhắc lại 'dùng pnpm', 'đừng đổi schema', 'chạy test này', 'trả lời tiếng Việt', bạn đang dùng trí nhớ ngắn hạn cho việc đáng lẽ phải nằm trong trí nhớ bền.

AGENTS.md là sổ tay vận hành của dự án dành cho agent. Nó không thay prompt hiện tại; nó làm nền để mọi prompt hiện tại không phải nhắc lại những điều ổn định.

• Nên viết hướng dẫn theo hành vi quan sát được: lệnh nào chạy, file nào đọc trước, thay đổi nào cần tránh.
• Nên tách quy tắc bền khỏi yêu cầu theo phiên. 'Luôn dùng tiếng Việt có dấu' thuộc AGENTS.md; 'viết bài về Codex hôm nay' thuộc prompt.
• AGENTS.md tốt có thứ tự ưu tiên. Khi hai quy tắc mâu thuẫn, Codex cần biết quy tắc nào thắng.
• Tài liệu hướng dẫn cũng cần bảo trì. Mỗi lần phát hiện một gotcha lặp lại, hãy thêm ngắn gọn vào file.

Công Thức 1: Chạy Quy Trình Chính

Khi dùng: bạn phải nhắc lại cùng một chuẩn làm việc qua nhiều phiên Codex.

1. Mở bằng mục đích dự án và các module chính.
2. Ghi lệnh thường dùng: cài đặt, build, test, kiểm tra nội dung.
3. Ghi vùng cấm: dữ liệu nhạy cảm, file không được tự ý đổi, thao tác cần xin quyền.
4. Ghi chuẩn phản hồi: ngôn ngữ, giọng, mức chi tiết, cách báo test.

Công Thức 2: Đóng Cổng Kiểm Chứng

Một phiên tốt không cần lúc nào cũng dài. Điều cần giữ là nhịp: giao việc rõ, để Codex đọc đúng, cho nó thực hiện trong phạm vi nhỏ, rồi bắt nó tự chứng minh kết quả.

Prompt Mẫu

# AGENTS.md tối giản
 
- Đọc README và package.json trước khi sửa.
- Ưu tiên thay đổi nhỏ, giữ API public ổn định.
- Chạy npm run build khi thay đổi ảnh hưởng giao diện.
- Báo rõ test đã chạy và rủi ro còn lại.

Ví Dụ Tối Thiểu: AGENTS.md tối giản

# AGENTS.md tối giản
 
- Đọc README và package.json trước khi sửa.
- Ưu tiên thay đổi nhỏ, giữ API public ổn định.
- Chạy npm run build khi thay đổi ảnh hưởng giao diện.
- Báo rõ test đã chạy và rủi ro còn lại.

Khi Có Lỗi

Nếu gặp một trong các lỗi trên, cách sửa thường không phải là viết prompt dài hơn. Cách sửa là thêm đúng mảnh còn thiếu: một đường dẫn ngữ cảnh, một ràng buộc phạm vi, hoặc một tiêu chí nghiệm thu.

Quy Trình Trong Đội

AGENTS.md nên được rà soát như tài liệu kỹ thuật. Khi một pull request đổi cách build hoặc đổi quy ước test, hãy xem có cần cập nhật hướng dẫn cho agent không.

Với đội mới bắt đầu, đừng đưa Codex vào khâu rủi ro nhất ngay. Hãy bắt đầu ở nơi có phản hồi nhanh: viết test, tạo bản nháp, rà link, chuẩn hóa tài liệu, tạo ảnh minh họa, hoặc chuẩn bị diff nhỏ để con người rà soát.

Bài Tập 30 Phút

1. Chọn một repo, bài viết hoặc màn hình thật để thực hành.
2. Viết một câu mục tiêu cho bài 3, tránh yêu cầu chung chung.
3. Liệt kê đúng ba nguồn context mà Codex nên đọc trước.
4. Ghi hai ràng buộc không được vượt.
5. Viết Done-when bằng bằng chứng có thể kiểm tra.
6. Chạy prompt trong Codex CLI hoặc Codex App.
7. Dừng sau plan đầu tiên và xem Codex có hiểu đúng không.
8. Cho Codex làm phần nhỏ nhất có thể.
9. Đóng gate: Đọc được, Hành động được, Kiểm được, Bảo trì được.
10. Ghi lại một điều nên đưa vào prompt hoặc AGENTS.md cho lần sau.

10 Điều Cần Nhớ

1. AGENTS.md giữ quy tắc bền của dự án.
2. Prompt giữ yêu cầu riêng của phiên hiện tại.
3. Quy tắc càng gần thư mục làm việc càng cụ thể.
4. Hướng dẫn tốt nói hành động, không nói khẩu hiệu.
5. Lệnh build/test phải được ghi rõ.
6. Vùng cấm quan trọng hơn phong cách đẹp.
7. Gotcha lặp lại nên được ghi lại ngay.
8. File hướng dẫn quá dài sẽ làm tín hiệu loãng.
9. Cập nhật AGENTS.md khi quy trình đổi.
10. Tài liệu cho agent cũng là tài liệu vận hành cho người.

Nguồn tham khảo chính: OpenAI Codex documentation. Bài tiếp: Sandbox và approvals: cho agent quyền vừa đủ.