Nếu phải nhắc lại “dùng pnpm”, “không sửa thư mục generated” và “chạy test trước khi kết thúc” ở mọi phiên, dự án đang thiếu một tệp hướng dẫn cho tác nhân. Codex tự đọc AGENTS.md theo phạm vi thư mục. Một tệp ngắn, cụ thể giúp giảm phỏng đoán và biến chuẩn của đội thành điều kiện làm việc nhất quán.
Kết quả sau bài học: Bạn sẽ viết được AGENTS.md cấp repository, biết khi nào cần tệp lồng trong thư mục con và kiểm tra Codex thực sự hiểu lệnh build, test và giới hạn.
Tư duy quan trọng trước khi bắt đầu
AI coding agent là cộng sự có khả năng thao tác, không phải nguồn chân lý. Bạn vẫn chịu trách nhiệm về mã được đưa vào dự án. Hãy giữ nhiệm vụ nhỏ, cung cấp bối cảnh vừa đủ, yêu cầu bằng chứng và không phê duyệt điều mình chưa hiểu.
Hướng dẫn từng bước
Bước 1: Đặt tệp ở đúng phạm vi
Tạo AGENTS.md ở thư mục gốc repository cho quy tắc dùng chung. Với monorepo, thư mục frontend hoặc backend có thể có AGENTS.md riêng. Hướng dẫn gần tệp đang làm việc hơn sẽ cụ thể hơn; đừng tạo nhiều tầng nếu quy tắc không khác nhau.
Bước 2: Ghi bản đồ dự án ngắn gọn
Liệt kê điểm vào, thư mục mã nguồn, test, migration, file sinh tự động và nơi đặt tài liệu. Không chép lại toàn bộ README. Mục tiêu là giúp agent biết nên đọc đâu trước và tránh đâu.
Bước 3: Ghi lệnh có thể chạy nguyên văn
Nêu lệnh cài đặt, dev, lint, type-check, unit test và test một tệp. Ghi luôn điều kiện phụ như cần database local. Câu “hãy test kỹ” kém hơn “chạy pnpm test và pnpm typecheck”.
Bước 4: Viết quy ước và ranh giới kiểm chứng được
Ví dụ: dùng TypeScript strict, component dùng PascalCase, không thêm dependency nếu chưa được duyệt, không sửa migration đã phát hành, không đọc tệp .env. Tránh quy tắc cảm tính như “code sạch”.
Bước 5: Thử bằng một phiên mới
Yêu cầu Codex chỉ đọc hướng dẫn rồi tóm tắt: cấu trúc, lệnh kiểm tra và vùng cấm. Giao một thay đổi nhỏ, xem kế hoạch và diff. Nếu nó hiểu sai, sửa câu hướng dẫn — đừng vá bằng một đoạn văn dài trong chat.
Bài thực hành có đầu ra rõ ràng
Bài tập: tạo AGENTS.md cho dự án Todo gồm React và API Node. Viết tối đa 80 dòng, có lệnh chạy riêng hai phần, quy tắc không chạm file migration và định nghĩa “hoàn thành”.
Tiêu chuẩn nộp bài: lưu prompt đã dùng, ảnh hoặc log kết quả trước/sau, diff cuối cùng, lệnh kiểm tra và ba điều bạn tự học được từ mã. Nếu test không chạy được, ghi lý do thay vì coi như đã đạt.
Prompt mẫu có thể sao chép
Đọc toàn bộ AGENTS.md áp dụng cho thư mục hiện tại. Tóm tắt build, test, conventions và do-not rules. Chưa sửa code.
Hãy kiểm tra AGENTS.md này: quy tắc nào mơ hồ, mâu thuẫn hoặc không thể kiểm chứng? Đề xuất bản rút gọn.
Trước khi kết thúc, đối chiếu diff và các lệnh đã chạy với định nghĩa Done trong AGENTS.md.
Lỗi người mới thường gặp
- Biến AGENTS.md thành tài liệu kiến trúc hàng trăm dòng
- Có lệnh đã lỗi thời hoặc không chạy trên máy mới
- Quy tắc cấp cha và cấp con mâu thuẫn
- Đặt bí mật, token hoặc dữ liệu cá nhân trong hướng dẫn
Checklist hoàn thành
- Đúng vị trí và phạm vi
- Dưới mức cần thiết, dễ quét
- Lệnh build/test chạy được
- Ranh giới cụ thể
- Đã kiểm tra bằng phiên mới
Cách tự học để không phụ thuộc AI
- Trước khi hỏi, tự dự đoán tệp và nguyên nhân trong năm phút.
- Sau câu trả lời, yêu cầu giải thích một khái niệm bạn chưa hiểu bằng ví dụ nhỏ.
- Tự viết lại phần cốt lõi hoặc test mà không nhìn câu trả lời.
- Lưu lỗi và bài học vào ghi chú dự án, không lưu bí mật.
- Một tuần sau, làm lại bài tập với yêu cầu hơi khác.
Kết luận: dùng tác nhân AI tốt không nằm ở việc tạo nhiều code, mà ở khả năng đặt mục tiêu rõ, kiểm soát phạm vi và chứng minh kết quả. Nếu giữ được vòng lặp đọc → kế hoạch → thay đổi nhỏ → test → review, người mới vừa đi nhanh hơn vừa thực sự tiến bộ.
Nguồn tham khảo chính thức: tài liệu sản phẩm dành cho nhà phát triển. Giao diện và tính năng có thể thay đổi; hãy đối chiếu tài liệu hiện hành khi cài đặt.
