Dùng AGENTS.md trong Codex để thống nhất quy tắc làm việc cho nhóm

Hai người trong nhóm cùng nhờ Codex sửa một website, nhưng người dùng npm, người dùng pnpm; người chạy kiểm tra, người bỏ qua. Trong khoảng 45 phút, bạn có thể tạo AGENTS.md ở gốc repo để Codex đọc cùng một quy tắc khi bắt đầu việc, rồi thử trên một yêu cầu nhỏ. Bạn cần quyền sửa repo, biết lệnh kiểm tra đang dùng và có người trong nhóm rà nội dung quy tắc.

AGENTS.md là tệp chỉ dẫn cho Codex, không phải tài liệu chỉ để người đọc tham khảo. Theo hướng dẫn chính thức của OpenAI, Codex đọc các tệp này trước khi làm việc và ghép hướng dẫn từ phạm vi chung tới thư mục hiện tại. Tệp đặt gần công việc chuyên biệt hơn sẽ có hiệu lực ưu tiên khi hướng dẫn xung đột. Với nhóm mới bắt đầu, một tệp ngắn ở gốc repo thường dễ kiểm tra hơn nhiều tệp lồng nhau.

Nếu chưa quen một lần làm việc với Codex, xem hướng dẫn sửa một chi tiết bằng Codex CLI và vibe coding cho người mới. Bài này tập trung vào cách cả nhóm đưa những điều đã thống nhất vào repo, để mỗi phiên Codex nhận cùng ngữ cảnh.

Chuẩn bị

Chọn một repo đang hoạt động và ghi ba điều nhóm biết chắc: cách cài phụ thuộc, lệnh kiểm tra, nơi ghi thay đổi. Mở README, cấu hình dự án và các bước kiểm tra trong CI để xác nhận. Đừng lấy một lệnh từng dùng ở repo khác làm quy tắc cho repo này.

Trước khi sửa, chạy git status --short và xem repo đã có AGENTS.md hay AGENTS.override.md chưa. Nếu có, đọc và hỏi người đang quản lý quy tắc đó. Với dự án chưa có tệp, tạo một nhánh nhỏ theo quy trình nhóm. Đừng đưa mật khẩu, khóa API, tên khách hàng hay dữ liệu riêng vào AGENTS.md, vì đây là tệp đi cùng mã nguồn.

Hãy chọn một thay đổi thử nghiệm có thể kiểm chứng trong vài phút, chẳng hạn sửa nhãn nút trên trang liên hệ. Nếu bạn cần học cách giao phạm vi cho AI, hướng dẫn viết prompt rõ mục tiêu giúp viết yêu cầu ngắn mà vẫn có tiêu chí nghiệm thu.

Làm từng bước

1. Viết quy tắc nhóm ở gốc repo

Tạo AGENTS.md với các điều có thể thực hiện và kiểm tra được. Ví dụ cho một website dùng pnpm:

# Working agreements

## Before editing
- Read the relevant page and its tests before changing code.
- Check `git status --short` and preserve existing changes.

## Implementation
- Use `pnpm` for package commands in this repository.
- Keep each change focused on the requested behavior.
- Do not edit generated files by hand.

## Verification
- Run `pnpm lint` after changing application code.
- Run the relevant test for the behavior you changed.
- Report the commands run, their results, and anything not checked.

Đây là ví dụ, không phải lệnh chuẩn cho mọi website. Hãy thay pnpm lint bằng lệnh thật của nhóm. Nếu không có test, viết rõ cách kiểm tra thủ công. Quy tắc “báo điều chưa kiểm tra” thường hữu ích hơn câu chung chung “hãy làm việc cẩn thận”.

Đừng nhét cả cẩm nang công ty vào tệp. OpenAI cho biết Codex có giới hạn kích thước tổng hướng dẫn, mặc định 32 KiB, và có thể bỏ qua phần sau khi đạt ngưỡng. Vì vậy, giữ tệp gốc ngắn, gắn đường dẫn tới tài liệu chuyên sâu khi cần. Tài liệu cấu hình giải thích cách phát hiện tệp và giới hạn này.

2. Thêm quy tắc riêng cho thư mục khi thật sự cần

Giả sử nhóm thanh toán có bộ kiểm tra khác phần còn lại. Trong services/payments/, tạo AGENTS.override.md để nói rõ việc riêng của thư mục đó. OpenAI mô tả rằng Codex đọc từ gốc dự án xuống thư mục làm việc, lấy tối đa một tệp chỉ dẫn trong mỗi thư mục. Ở cùng thư mục, tệp AGENTS.override.md được ưu tiên trước AGENTS.md.

# Payments working agreements

- Run `make test-payments` after changing payment behavior.
- Ask the payment owner to review changes to prices or checkout flows.
- Explain any migration before proposing it.

Chỉ thêm tầng này nếu nhóm thật sự có khác biệt. Với quy tắc dùng chung, chỉnh tệp gốc. Khi có hai chỉ dẫn mâu thuẫn, hướng dẫn ở thư mục gần công việc hơn xuất hiện sau trong chuỗi mà Codex đọc. Bạn vẫn nên viết rõ quy tắc thay thế, thay vì bắt người đọc tự suy luận từ hai câu trái nhau.

3. Mở phiên Codex mới và kiểm tra tệp được đọc

Theo hướng dẫn AGENTS.md, Codex dựng chuỗi chỉ dẫn khi khởi động, thường một lần cho mỗi phiên terminal. Nếu vừa sửa tệp, hãy mở phiên mới từ đúng thư mục và yêu cầu Codex nêu nguồn chỉ dẫn:

Hãy liệt kê các tệp chỉ dẫn đang có hiệu lực trong thư mục này, theo thứ tự được đọc. Tóm tắt quy tắc về trình quản lý gói, cách kiểm tra và việc giữ thay đổi sẵn có. Chỉ đọc, không sửa tệp.

So câu trả lời với nội dung thực tế. Nếu Codex không thấy quy tắc mới, kiểm tra bạn có đứng trong đúng repo không, có tệp override nào đang thay thế không và phiên đã được khởi động lại chưa. Đừng kết luận quy tắc đã hoạt động chỉ vì tệp tồn tại trong Git.

4. Cho cả nhóm thử cùng một việc nhỏ

Giao một yêu cầu thử với tiêu chí rõ ràng. Ví dụ:

Trong repo hiện tại, tìm nguồn của nhãn nút Gửi trên trang liên hệ. Chỉ đổi chữ sai chính tả ở nhãn này. Trước khi sửa, nêu tệp dự định đổi. Sau khi sửa, làm theo AGENTS.md để kiểm tra, rồi báo diff, lệnh đã chạy, kết quả và điều chưa kiểm tra. Không đụng tệp đang có thay đổi sẵn.

Nhờ hai thành viên thử trên nhánh riêng, rồi so kết quả: Codex có dùng đúng trình quản lý gói, có tránh tệp đang sửa dở, có chạy kiểm tra phù hợp và báo giới hạn không? Đọc git diff, trạng thái Git và kết quả thật. Nếu một quy tắc bị hiểu khác nhau, sửa câu đó cho cụ thể hơn. Đừng chỉ thêm nhiều câu cảm tính.

5. Rà lại theo thay đổi của repo

Khi CI đổi từ npm sang pnpm, khi thư mục được chuyển, hoặc khi thêm bước duyệt, cập nhật AGENTS.md cùng thay đổi đó. Chọn người sở hữu tệp, để mỗi pull request sửa quy tắc được nhóm liên quan đọc. Có thể thêm mục ## Code Review Rules để Codex chú ý các lỗi nghiệp vụ khi review trên GitHub; OpenAI hướng dẫn nên mô tả hành vi cần bắt và đường xử lý an toàn, còn kiểm tra định dạng nên để CI.

Nếu quy trình lặp lại gồm nhiều bước, mã và tài liệu mẫu, hãy xem cách dùng Codex Skills để tái sử dụng quy trình. AGENTS.md thích hợp cho quy tắc chung của repo; skill thích hợp cho một công việc cụ thể có thể gọi lại.

Kết quả mẫu

Một lượt thử tốt có thể trả về: “Đã đọc AGENTS.md ở gốc repo. Nhãn sai nằm trong tệp bản dịch của trang liên hệ. Tôi sửa một chuỗi, không đụng hai tệp đang sửa dở. pnpm lint và test liên quan đều thành công. Diff chỉ chứa nhãn vừa đổi. Chưa kiểm tra trên trình duyệt vì môi trường thử chưa chạy được.” Nhóm vẫn cần nhìn diff và thử giao diện nếu đó là tiêu chí giao việc.

Mẹo để kết quả tốt hơn

Viết quy tắc theo dạng khi nào, làm gì, bằng chứng nào. “Sau khi đổi ứng dụng, chạy pnpm lint và báo kết quả” rõ hơn “luôn đảm bảo chất lượng”. Ghi lệnh thật trong repo; đường dẫn sai làm Codex lặp lại sai lầm cho nhiều thành viên.

Nếu có nhiều thư mục, chỉ dùng tệp lồng nhau cho sự khác biệt ổn định. Kiểm tra một phiên từ gốc và một phiên từ thư mục chuyên biệt. Đây là cách nhìn thấy quy tắc nào được tải trong từng tình huống.

Giới hạn cần biết

AGENTS.md là hướng dẫn bằng lời, không phải cơ chế cấp quyền hay chặn lệnh. Đừng viết “không được truy cập mạng” trong tệp rồi cho rằng mạng đã bị khóa. Quyền thực tế phụ thuộc sandbox, chính sách phê duyệt và cấu hình của phiên. Tài liệu Rules nói các tệp .rules dùng để điều khiển lệnh chạy ngoài sandbox, hiện còn ở trạng thái thử nghiệm và có phạm vi áp dụng riêng. Người quản trị nên chọn cơ chế quyền phù hợp thay vì xem lời dặn trong repo là hàng rào bảo mật.

Codex vẫn có thể hiểu sai quy tắc hoặc sửa sai chỗ. Một hướng dẫn tốt giúp giảm sự khác biệt giữa các phiên, nhưng không chứng minh kết quả đúng. Giữ bước review và kiểm tra thực tế cho thay đổi ảnh hưởng dữ liệu, tiền, quyền truy cập hoặc trải nghiệm khách hàng.

Câu hỏi thường gặp

Nên đặt AGENTS.md ở đâu? Đặt ở gốc repo cho quy tắc chung. Chỉ thêm tệp ở thư mục con khi nhóm đó có quy trình khác cần áp dụng gần mã của họ.

Codex có đọc lại tệp ngay giữa phiên không? Hướng dẫn chính thức nói chuỗi chỉ dẫn được tạo khi bắt đầu lượt chạy, thường ở lúc mở phiên terminal. Hãy mở phiên mới sau khi sửa để kiểm tra quy tắc vừa cập nhật.

Tệp override khác gì tệp thường? Trong cùng một thư mục, Codex kiểm tra AGENTS.override.md trước AGENTS.md và chỉ lấy một tệp. Dùng override khi thật sự muốn thay hướng dẫn tại phạm vi đó.

Viết quy tắc bằng tiếng Việt được không? Có thể viết bằng ngôn ngữ cả nhóm dễ rà nhất. Với repo đa quốc gia, cân nhắc tiếng Anh và giải thích thuật ngữ để người quản lý tệp cùng hiểu. Nội dung quan trọng là lệnh, phạm vi và tiêu chí rõ ràng.

Có thay được quyền truy cập bằng một câu cấm trong tệp không? Không. Quy tắc trong AGENTS.md hướng Codex cách làm việc, còn giới hạn truy cập cần được đặt ở cơ chế quyền và môi trường phù hợp.

Tài liệu OpenAI được đối chiếu ngày 04/10/2026. #Codex #AGENTSmd #LamViecNhom #VibeCoding