Claude Code đã đọc AGENTS.md: một file hướng dẫn cho mọi AI coding tool
Tóm tắt
Team dùng nhiều AI coding tool thường phải duy trì nhiều file cấu hình (CLAUDE.md, .cursor/rules, AGENTS.md…). Claude Code giờ đọc AGENTS.md khi thư mục không có CLAUDE.md, nên một file hướng dẫn có thể dùng chung cho nhiều tool.
Team dùng nhiều công cụ AI lập trình thường phải duy trì nhiều file hướng dẫn gần như giống nhau: CLAUDE.md cho Claude Code, .cursor/rules cho Cursor, AGENTS.md cho các công cụ khác. Mỗi lần đổi quy ước, phải sửa nhiều nơi — và chúng dần lệch nhau. Claude Code nay đã đọc AGENTS.md khi thư mục không có CLAUDE.md, nên một file hướng dẫn có thể dùng chung cho nhiều công cụ.
Những gì thay đổi
| Điểm | Chi tiết |
|---|---|
| Phiên bản | Claude Code 2.1.277 |
| Thứ tự ưu tiên | CLAUDE.md được ưu tiên; AGENTS.md chỉ được dùng ở thư mục không có CLAUDE.md |
| Tuỳ chỉnh | Dùng /config để chọn đọc AGENTS.md, CLAUDE.md hoặc cả hai |
| Ngoại lệ | Cần phiên lấy được feature flag từ Anthropic; khi chạy qua Bedrock/nhà cung cấp khác hoặc tắt telemetry sẽ quay về CLAUDE.md |
| AGENTS.md | Chuẩn mở, Markdown thuần, đặt ở root repo; do Agentic AI Foundation (thuộc Linux Foundation) quản lý |
Nên viết gì trong AGENTS.md?
Đây là tài liệu cho “đồng nghiệp mới” — người hay máy — cần biết để làm việc trong repo:
- Lệnh quan trọng: cài đặt, build, chạy test, lint, chạy một test đơn lẻ.
- Cấu trúc thư mục: phần nào là code chính, phần nào là sinh tự động, đừng sửa.
- Quy ước code: đặt tên, định dạng, cách xử lý lỗi, thư viện được/không được dùng.
- Quy trình: cách đặt tên nhánh, format commit, yêu cầu trước khi mở PR.
- Điều cấm kỵ: không đụng vào migration cũ, không commit secret, không sửa file X.
# AGENTS.md
## Build & test
- Cài đặt: `pnpm install`
- Test: `pnpm test` (một file: `pnpm test path/to/file`)
- Lint: `pnpm lint` — phải sạch trước khi commit
## Quy ước
- TypeScript strict; không dùng `any` nếu không có comment giải thích
- Component đặt trong `src/components/<Name>/`
## Không làm
- Không sửa `src/generated/` (sinh tự động)
- Không commit file `.env`Chiến lược cho repo dùng nhiều công cụ
- Đưa phần hướng dẫn chung vào AGENTS.md.
- Giữ CLAUDE.md mỏng cho phần chỉ Claude dùng (hook, skill, subagent, quyền), và trỏ sang AGENTS.md cho phần chung.
- Kiểm tra trên từng công cụ: cùng một hướng dẫn có thể được hiểu khác nhau giữa các agent.
- Đặt AGENTS.md vào quy trình review như tài liệu quan trọng, không phải ghi chú tuỳ ý.
Lưu ý
- Giữ ngắn: file hướng dẫn được nạp vào ngữ cảnh. Càng dài càng tốn token và càng dễ bị bỏ qua; chỉ ghi những gì agent không thể tự suy ra.
- Tránh mâu thuẫn: nếu cùng thư mục có cả hai file, CLAUDE.md thắng; đừng để hai file nói hai điều khác nhau.
- Kiểm tra môi trường: nếu team dùng Bedrock hoặc tắt telemetry, hành vi đọc AGENTS.md có thể khác; thử thực tế thay vì giả định.
Áp dụng thế nào?
- Dev: chuyển nội dung chung từ CLAUDE.md sang AGENTS.md, để lại phần riêng cho Claude.
- Tech Lead: coi AGENTS.md như tài liệu onboarding — viết cho cả người lẫn máy đọc; bài kiểm tra tốt là hỏi một người mới xem họ có làm được việc nhờ nó không.
- PM: một nguồn sự thật duy nhất giảm chi phí duy trì khi team đổi hoặc thêm công cụ AI.