Rule cho AI coding agent: CLAUDE.md, AGENTS.md và Agent Skills
Rule cho AI coding agent là các file như CLAUDE.md, AGENTS.md và Agent Skills giúp agent bám kiến trúc, bớt lặp lệnh. Vì sao nhồi quá nhiều rule lại phản tác dụng và cách làm đúng.
Rule cho AI coding agent là những chỉ dẫn bền vững bạn đặt sẵn để agent lập trình (Claude Code, Cursor, Codex, Antigravity) bám đúng kiến trúc, quy ước và lệnh build/test của dự án, thay vì phải nhắc lại mỗi phiên. Ba dạng phổ biến nhất là file CLAUDE.md, file AGENTS.md và Agent Skills. Cả ba nhắm cùng một đích: đưa quy tắc xác định vào một agent vốn không xác định.
CLAUDE.md và AGENTS.md khác gì nhau?
CLAUDE.md do Claude Code phổ biến: một file markdown ở gốc repo, cung cấp bối cảnh dự án, lệnh build/test và ràng buộc hành vi. AGENTS.md là chuẩn chung nhiều công cụ đọc trực tiếp, như Codex, Cursor, Copilot coding agent, Windsurf, Kiro và Antigravity: một file cho nhiều agent.
Hai điểm dễ nhầm. Claude Code chỉ đọc CLAUDE.md, không đọc AGENTS.md (theo tài liệu memory của Anthropic). Gemini CLI mặc định đọc GEMINI.md và chỉ đọc AGENTS.md khi bạn cấu hình. Vì vậy nhiều dự án giữ CLAUDE.md với dòng đầu là @AGENTS.md, hoặc giữ hai file có nội dung giống hệt, để các công cụ không lệch nhau.
Vì sao nhồi quá nhiều rule lại làm agent tệ đi?
Nhiều người than "AI bỏ qua rule của tôi". Gốc rễ thường là một trong hai lỗi đối nghịch: nhét mọi rule vào một file khổng lồ, nuốt sạch ngữ cảnh (token bloat) và làm model loãng; hoặc giấu rule trong một skill không bao giờ được gọi nên chưa từng được nạp.
Nguyên tắc: rule nào phải đúng mọi lúc thì đặt ở chỗ luôn được nạp, như @-import trong CLAUDE.md. Rule để router quyết định chỉ là best-effort, vì việc đọc nó vẫn phụ thuộc quyết định của model. Cái giá của chỗ luôn được nạp là mọi file ở đó tính phí ở mọi phiên, kể cả phiên không đụng đến code, nên chỉ những rule thật sự phải đúng mọi lúc mới xứng đáng ở đó. Nhồi thêm không bằng đặt đúng chỗ.
@~/.aki/akidevrule/index.md
@~/.aki/akidevrule/RULE-agent-behavior.md
@~/.aki/akidevrule/RULE-coding.md
@~/.aki/akidevrule/RULE-pattern-core.md
@~/.claude/skills/akirule/SKILL.mdĐoạn trên là phần đầu ~/.claude/CLAUDE.md của AkiDevRule: mỗi dòng một đường dẫn, và Claude Code nạp từng file khi khởi động phiên.
Agent Skills: nạp rule đúng lúc thay vì nhồi hết
Agent Skills giải bài toán token bloat bằng tiết lộ dần (progressive disclosure): agent chỉ giữ sẵn phần mô tả ngắn của mỗi skill, và chỉ nạp toàn bộ nội dung khi tác vụ khớp. Một bộ router đọc tín hiệu trong yêu cầu rồi mới kéo đúng rule cần, nhờ vậy ngữ cảnh gọn mà vẫn đủ luật.
Làm sao có baseline rule tốt mà không tự dựng từ đầu?
AkiDevRule là baseline mã nguồn mở (MIT) làm sẵn việc này cho Claude Code và Antigravity. Một lệnh cài, npx @akinet/akidevrule@latest, cho bạn một kho rule tự định tuyến: năm file luôn nạp (index.md, ba file rule lõi và router akirule), phần còn lại chỉ đọc khi tác vụ khớp, cùng mười skill, mỗi skill lo một việc. Đúng nguyên tắc ở trên: luật bắt buộc thì @-import, luật theo bối cảnh thì router.
Viết rule tốt không chỉ là thêm luật mà còn là quản trị agent: chống một agent tự duyệt việc của mình (role collapse), chống nịnh (sycophancy) và đặt cổng kích hoạt cho hội đồng agent. Đọc thêm giải pháp chống sycophancy và cổng kích hoạt agent council.