Mục lục bài viết
Buổi sáng, bạn nhờ Codex thêm mục Câu hỏi thường gặp vào một ứng dụng web nhỏ. Bạn đã dặn Codex phải mở bản Preview xem thử trên máy, rồi mới được báo là đã xong. Bạn cũng dặn nó không được sửa file noi-dung-trang-chu.md. Buổi chiều, bạn mở tiếp chính dự án đó bằng Claude Code để chỉnh sửa. Nếu instruction cho Codex nằm ở AGENTS.md, còn instruction cho Claude Code nằm ở CLAUDE.md và nội dung 2 file không khớp nhau, bạn sẽ phải nhớ xem tool nào đang làm theo instruction nào.
AGENTS.md và CLAUDE.md đều là file ghi instruction để tool AI biết cách làm việc trong dự án. Trong đó, Codex đọc AGENTS.md, còn Claude Code vốn quen dùng CLAUDE.md. Tuy nhiên, các phiên bản Claude Code mới cũng đã đọc được AGENTS.md trong một số trường hợp nhất định. Do đó, bạn hoàn toàn có thể chỉ ghi một lần cho cả 2 tool vào một file duy nhất, rồi bổ sung thêm instruction riêng khi thật sự cần thiết.
Biết tool nào đọc file nào giúp bạn tránh một lỗi khó nhận ra: bạn tưởng đã dặn cả 2 tool, trong khi một tool chưa hề nhận được instruction đó. Ngay cả khi tool đã đọc file, bạn vẫn cần tự xem kết quả trên màn hình để biết agent có làm đúng như bạn đã dặn hay không.
1. AGENTS.md và CLAUDE.md là gì?
AGENTS.md là file hướng dẫn cách làm việc dành cho các tool lập trình AI trong dự án. Trang web AGENTS.md ví file này như một bản README dành cho agent, nơi bạn ghi bối cảnh dự án và các quy ước mà tool cần biết trước khi làm. Chẳng hạn với một ứng dụng web, bạn có thể ghi rõ mục tiêu của dự án, cách kiểm tra Preview, phần nào được phép sửa và file nào bắt buộc phải giữ nguyên.
Trong khi đó, CLAUDE.md cũng là file instruction tương tự, nhưng được thiết kế riêng cho Claude Code. Theo tài liệu của Anthropic, Claude Code sẽ đọc file này ngay khi bắt đầu một session (một phiên làm việc với agent). Bạn có thể dùng file này để lưu những chỉ dẫn thường phải nhắc lại, từ quy ước chung của dự án cho đến cách kiểm tra kết quả trước khi tool báo hoàn thành.
Tuy nhiên, bạn rất dễ nhầm AGENTS.md với subagent của Claude Code, tức các agent phụ nằm trong thư mục .claude/agents/. AGENTS.md là file instruction cho cả dự án, còn subagent là agent phụ bạn tạo thêm để giao riêng từng task.
2. Codex và Claude Code đọc file instruction thế nào?
Trước khi bắt tay vào việc, Codex luôn tìm đọc file AGENTS.md. Tool này quét instruction từ thư mục gốc của dự án xuống dần tới thư mục bạn đang làm việc. Nếu bạn đặt thêm file ở thư mục con, Codex nạp file đó sau, nên instruction trong đó ghi đè instruction ở thư mục gốc. Tại mỗi thư mục, Codex ưu tiên tìm AGENTS.override.md trước AGENTS.md, nếu đã thấy file ghi đè thì nó bỏ qua file còn lại. Mặc định Codex chỉ nạp tối đa 32 KiB cho tất cả các file đó cộng lại, chứ không phải 32 KiB cho mỗi file.
Trong khi đó, Claude Code lại tìm đọc CLAUDE.md và CLAUDE.local.md ở thư mục bạn đang làm việc và các thư mục cha. Codex để file ở thư mục con ghi đè file ở thư mục gốc, còn Claude Code gộp nội dung của mọi file nó tìm được vào cùng một session. File ở thư mục con chỉ được nạp khi Claude Code đọc tới một file trong thư mục đó.
Từ phiên bản v2.1.277, Claude Code có thể đọc thẳng file AGENTS.md nếu dự án hoàn toàn không có CLAUDE.md, .claude/CLAUDE.md hay CLAUDE.local.md. Mặc định là như vậy, nhưng bạn vẫn đổi được cách chọn file trong phần Project instructions ở /config, tức chỗ chọn file instruction mà Claude Code sẽ đọc. Còn nếu trong thư mục có một trong các file của Claude Code vừa nêu thì Claude Code chỉ đọc các file đó và bỏ qua AGENTS.md. Muốn Claude Code đọc cả AGENTS.md, bạn nhúng nội dung file này vào CLAUDE.md bằng dòng @AGENTS.md, hoặc đổi cài đặt trong phần Project instructions.
2 tool đọc file như sau:
| File trong dự án | Codex | Claude Code mặc định (từ v2.1.277) |
|---|---|---|
Chỉ có AGENTS.md |
Đọc instruction trong AGENTS.md |
Đọc AGENTS.md do không tìm thấy file Claude ở thư mục đang làm hay thư mục cha |
Có cả AGENTS.md và CLAUDE.md |
Chỉ đọc AGENTS.md |
Chỉ đọc file Claude; không tự ghép thêm AGENTS.md |
CLAUDE.md có dòng @AGENTS.md |
Chỉ đọc AGENTS.md |
Đọc CLAUDE.md và nạp thêm nội dung dẫn từ AGENTS.md sang |
Codex có hỗ trợ file AGENTS.override.md, còn Claude Code thì không đọc file này. Vì vậy, nếu instruction "không sửa file noi-dung-trang-chu.md" chỉ nằm trong AGENTS.override.md, bạn đừng mặc định là Claude Code cũng đã thấy nó.
3. Nên dùng AGENTS.md hay CLAUDE.md?
Nếu chỉ dùng Codex cho dự án, bạn hãy ghi toàn bộ instruction chung vào file AGENTS.md. Trong trường hợp dùng song song cả Codex và Claude Code (phiên bản có hỗ trợ đọc trực tiếp AGENTS.md), bạn vẫn có thể bắt đầu với duy nhất file AGENTS.md. Cách này chỉ đúng khi dự án CHƯA CÓ CLAUDE.md, .claude/CLAUDE.md hay CLAUDE.local.md, và phần Project instructions vẫn cho phép đọc AGENTS.md. Bạn hãy kiểm tra 2 điều này trên máy trước khi giao việc.
Khi bạn cần một file CLAUDE.md riêng, bạn chèn dòng @AGENTS.md vào ngay đầu file đó. Bạn cứ gom toàn bộ instruction chung vào AGENTS.md, chẳng hạn phải mở Preview rồi mới báo hoàn thành, và không được sửa file noi-dung-trang-chu.md. Bên dưới dòng @AGENTS.md, bạn chỉ ghi instruction riêng cho Claude Code. Nhờ cách làm này, mỗi khi cần thay đổi instruction chung, bạn chỉ phải chỉnh sửa ở đúng một nơi.
Bạn cũng có thể giữ 2 file riêng nếu muốn dặn mỗi tool một kiểu khác nhau. Đổi lại, mỗi khi cần sửa một quy ước chung, bạn buộc phải cập nhật thủ công trên cả 2 file. Sai sót phổ biến nhất là bạn ghi cùng một instruction ở 2 nơi rồi chỉ sửa một bên. Buổi sáng Codex làm theo bản mới, đến chiều Claude Code vẫn chạy theo instruction cũ.
4. Hướng dẫn dùng một file instruction cho cả Codex và Claude Code
Nếu bạn đang thêm mục Câu hỏi thường gặp cho website, bạn chỉ cần vài instruction ngắn và dễ kiểm tra:
# Instruction cho dự án
- Chỉ sửa mục Câu hỏi thường gặp trong yêu cầu này.
- Xem lại Preview trước khi báo hoàn thành.
- Không sửa file `noi-dung-trang-chu.md`.
- Khi báo xong, liệt kê các file đã thay đổi.
Đoạn mẫu trên là instruction cho một dự án giả định để bạn dễ hình dung. Khi áp dụng, bạn hãy thay bằng tên file và phần việc có thật trong dự án của mình. Câu dặn "không sửa file" chỉ cho agent biết ý bạn, không khoá được quyền sửa file đó.
Bước 1. Tạo file AGENTS.md tại thư mục gốc của dự án. Bạn dán toàn bộ instruction chung vào file này rồi lưu lại. Để file ở thư mục gốc thì cả 2 tool đều tìm thấy nó ngay khi bạn mở dự án. Nếu dự án đã có sẵn file AGENTS.md, bạn hãy sửa ngay trên file đó, đừng tạo thêm một file instruction chung ở chỗ khác.
Bước 2. Kiểm tra instruction Codex đang áp dụng. Trước tiên, bạn mở một session Codex mới trong đúng thư mục dự án. Tiếp theo, bạn gõ câu hỏi: “Hãy tóm tắt các instruction của dự án mà bạn đang dùng, và cho biết chúng đến từ file nào.” Bạn hãy đối chiếu câu trả lời của Codex với 2 yêu cầu quan trọng nhất, chẳng hạn việc mở Preview rồi mới báo xong và giữ nguyên file trang chủ. Câu trả lời của agent chỉ là một dấu hiệu, chưa phải bằng chứng nó sẽ làm đúng.
Bước 3. Xác định file instruction Claude Code đang nạp. Bạn mở một session Claude Code mới trong dự án. Nếu dự án chỉ có file AGENTS.md và đang dùng thiết lập mặc định, ngay khi session vừa mở, màn hình sẽ hiện dòng: no CLAUDE.md found; AGENTS.md loaded. Từ phiên bản Claude Code v2.1.280 trở đi, bạn có thể gõ lệnh /context để xem danh sách Memory files, tức các file instruction Claude Code đang nạp. Nếu dùng bản cũ hơn, bạn hãy hỏi thẳng Claude Code xem nó đang theo instruction nào rồi so lại với nội dung trong AGENTS.md. Nếu Claude Code không nạp AGENTS.md, bạn xem lại phiên bản đang dùng, rồi tìm trong thư mục dự án và các thư mục cha xem có CLAUDE.md hay CLAUDE.local.md không. Sau đó bạn mở /config xem phần Project instructions đang chọn file nào.
Bước 4. Bổ sung file CLAUDE.md khi có nhu cầu riêng. Khi Claude Code không tự nạp AGENTS.md, hoặc khi bạn muốn dặn riêng cho tool này vài điều, bạn hãy tạo file CLAUDE.md nằm cùng thư mục với AGENTS.md và điền nội dung sau:
@AGENTS.md
# Riêng cho Claude Code
- Báo rõ nếu không mở được Preview.
Sau khi lưu file, bạn mở một session mới để xem Claude Code đã nạp instruction chưa. Nếu bạn chỉ cần instruction chung và Claude Code đã tự nhận AGENTS.md, bạn không cần tạo thêm CLAUDE.md.
Bước 5. Kiểm lại kết quả trên trang web. Khi agent báo đã thêm xong mục Câu hỏi thường gặp, bạn hãy mở Preview để xem mục mới có hiện ra đúng chỗ không. Đồng thời, bạn kiểm tra danh sách file đã thay đổi để chắc chắn file trang chủ không bị sửa.
5. Vì sao agent vẫn không làm theo file instruction?
Trước khi chỉnh lại file, bạn cần biết agent chưa đọc được instruction hay đã đọc mà vẫn làm sai, vì 2 trường hợp này phải xử lý theo 2 cách khác nhau. Dưới đây là những lý do thường gặp:
- File chưa được nạp: Bạn có thể đã mở session ở sai thư mục, lưu file ở vị trí tool không quét tới, hoặc tạo file
AGENTS.mdsau khi session đã bắt đầu. Hãy kiểm tra lại vị trí lưu file và chủ động tạo một session mới. Theo tài liệu OpenAI, Codex chỉ đọc lại các file instruction ở mỗi lượt chạy, hoặc khi bạn mở một session mới. - Ưu tiên đọc file riêng của Claude Code: Nếu trong dự án đã có sẵn file
CLAUDE.md,.claude/CLAUDE.mdhoặcCLAUDE.local.md, tool này sẽ mặc định đọc các file đó thay vì tìm đếnAGENTS.md. Để xử lý, bạn có thể thêm dòng@AGENTS.mdvào bên trongCLAUDE.md, hoặc xem lại mục Project instructions. Nếu Claude Code trên máy bạn cũ hơn bản v2.1.277 thì nó chưa đọc đượcAGENTS.md. Bạn hãy cập nhật lên bản mới nhất. - Xung đột giữa các file instruction trong Codex: Trong cùng một thư mục, Codex luôn ưu tiên tìm file
AGENTS.override.mdtrướcAGENTS.md. Instruction bạn viết trong thư mục con cũng có thể trái với instruction ở thư mục gốc. Bạn hãy xem lại file instruction ở thư mục gốc và ở từng thư mục con dẫn tới thư mục bạn đang làm việc. - Nội dung instruction quá dài hoặc mâu thuẫn: Mặc định Codex chỉ nạp tối đa 32 KiB instruction. Với Claude Code, Anthropic cũng khuyên bạn nên viết instruction ngắn gọn, cụ thể và có cấu trúc rõ ràng. Nếu file chứa quá nhiều instruction cũ hoặc 2 file instruction nói trái ngược nhau, bạn hãy lược bớt và chỉ giữ lại những điều cốt lõi bạn muốn agent luôn ghi nhớ.
- Agent đã đọc nhưng vẫn làm sai: File instruction chỉ nói cho agent biết bạn muốn gì, và theo Anthropic, nó không chặn được agent làm việc khác. Muốn chặn hẳn việc agent sửa file đó thì phải dùng PreToolUse hook, tức một đoạn cấu hình chạy trước mỗi lần agent gọi tool và chặn chính lệnh đó lại. Nếu bạn không đọc code, việc bạn làm được ngay là giữ một bản gốc của file quan trọng, xem danh sách file đã đổi, và mở Preview rồi mới nhận kết quả.
6. Kết luận
AGENTS.md là nơi thuận tiện nhất để ghi instruction chung khi bạn làm cùng một dự án bằng cả Codex lẫn Claude Code. Claude Code bản mới đọc được file này nếu dự án không có CLAUDE.md hay CLAUDE.local.md, còn khi cần giữ CLAUDE.md thì bạn chỉ việc thêm dòng @AGENTS.md. Trước lần giao việc tiếp theo, bạn hãy kiểm tra xem tool đã nhận đúng instruction chưa, rồi mở Preview và soát lại danh sách file đã đổi.
Nguồn tham khảo
Tác giả
Bài viết liên quan
