Một thư mục .claude, mười tám đích cài đặt: AgentKits xử lý vấn đề phân mảnh cấu hình AI như thế nào

Một vấn đề mà mỗi công cụ lập trình AI lại giải quyết theo một cách khác nhau

Trong phần lớn năm 2024 và 2025, mỗi công cụ lập trình AI tự nghĩ ra cách riêng để nói cho agent biết codebase hoạt động ra sao: Claude Code đọc CLAUDE.md, Cursor đọc .cursorrules (sau này là .cursor/rules), Windsurf đọc .windsurfrules, GitHub Copilot đọc .github/copilot-instructions.md. Một repo mã nguồn mở muốn dùng được trên nhiều công cụ cùng lúc thì phải duy trì song song nhiều tệp gần như giống hệt nhau. Tháng 8 năm 2025, OpenAI đề xuất một giải pháp — AGENTS.md, một quy ước trung lập không phụ thuộc nhà cung cấp, hiện do Agentic AI Foundation thuộc Linux Foundation quản lý và được Codex, Cursor, Gemini CLI cùng nhiều công cụ khác đọc trực tiếp. Song song đó, một nỗ lực cộng đồng khác là Agent Rules cũng đặt cược tương tự nhưng theo hướng khác: định nghĩa hướng dẫn một lần duy nhất, để mỗi công cụ tự đưa nó vào ngữ cảnh riêng của mình.

AgentKits — bộ công cụ agent AI mã nguồn mở, giấy phép MIT của chúng tôi, hiện đã hoàn thiện Marketing Kit (18 agent, 93 lệnh, 28 skill) — nằm ngay ở hạ nguồn của chính vấn đề phân mảnh này. Chúng tôi đã xem trình cài đặt của nó thực sự xử lý vấn đề này ra sao, bởi “cứ dùng AGENTS.md rồi xong” hóa ra chỉ là một phần câu trả lời khi một dự án cam kết hỗ trợ nhiều hơn một vài công cụ.

Mười tám nền tảng, trong đó ba được ưu tiên

Việc hỗ trợ nền tảng của trình cài đặt không được viết cứng theo từng công cụ. Nó được khai báo trong một tệp YAML duy nhất, platform-codes.yaml, và một IdeManager dùng chung sẽ tự động tải handler cho mỗi mục được khai báo trong đó. Đọc trực tiếp tệp này cho thấy có 18 nền tảng được khai báo — không chỉ 5 cái được nêu tên trong mô tả gói npm (Claude Code, Cursor, GitHub Copilot, Windsurf, Cline), mà còn có Gemini CLI, Roo Code, Trae, OpenCode, Auggie, QwenCoder, Kilo Code, Codex CLI, Rovo Dev, Google Antigravity, Crush, iFlow, và Kiro. Ba trong số đó được đánh dấu preferred và hiển thị đầu tiên trong trình cài đặt: Claude Code, Cursor, và Windsurf.

Điều quan trọng là: dù chọn nền tảng nào, toàn bộ nội dung — mọi agent và mọi skill — luôn được sao chép nguyên vẹn vào .claude/agents/ và .claude/skills/. Thư mục đó là nguồn gốc chuẩn duy nhất. Điều khác biệt theo từng nền tảng nằm ở bước tiếp theo.

Launcher, không phải bản sao

Đối với các lệnh (commands), trình cài đặt không nhân bản nội dung thành 18 định dạng khác nhau. Thay vào đó, nó tạo ra một tệp “launcher” ngắn, theo đúng hình dạng mà công cụ đích mong đợi, trỏ ngược về tệp thật trong .claude/commands/. Logic tạo tệp thử lần lượt một chuỗi tên mẫu — {type}-command.md, {type}-command.toml, {type}-rule.md, {type}-steering.md, {type}-modes.yaml — và quay về một mẫu mặc định nếu không cái nào khớp.

Kết quả thực sự khác nhau về giọng điệu và hình thức theo từng công cụ, chứ không chỉ khác tên tệp. Launcher của Windsurf khai báo cascade: true trong frontmatter và nêu rõ hướng dẫn bốn bước: tải tệp workflow, đọc toàn bộ, làm theo từng bước, báo cáo tiến độ. Mẫu mặc định thì thẳng thừng hơn — “ĐIỀU CỰC KỲ QUAN TRỌNG LÀ BẠN PHẢI LÀM THEO LỆNH NÀY” — vì nó không có cơ chế riêng của công cụ nào để dựa vào. GitHub Copilot nhận ba đích xuất riêng biệt thay vì một (.github/agents/*.agent.md, .github/instructions/, và một tệp gốc trong .github), khớp với cách Copilot tự phân chia giữa định nghĩa agent và instructions. Roo Code cũng tương tự, nhận hai đích — .roo/rules-agentkits/ và một tệp .roomodes ở gốc — phản ánh cách Roo tự phân biệt giữa “rules” và “modes”. Ngược lại, Kilo Code gộp tất cả vào một tệp YAML duy nhất, .kilocodemodes, ở gốc dự án thay vì từng tệp theo lệnh.

AGENTS.md thực sự phù hợp ở đâu

Trong số mười tám nền tảng, có hai nền tảng — OpenCode và Codex CLI — hoàn toàn không dùng định dạng riêng. Đích cài đặt của chúng đặt template_type: agents_md, và tệp cấu hình nền tảng ghi thẳng nhãn “AGENTS.md standard format” (định dạng chuẩn AGENTS.md): một tệp AGENTS.md duy nhất ở gốc, được cập nhật tại chỗ. Vậy nên AgentKits không hề bỏ qua chuẩn mà OpenAI đề xuất — nó dùng đúng chuẩn đó ở nơi hệ sinh thái công cụ đã thực sự đọc nó, và dùng định dạng gốc riêng của từng công cụ ở mọi nơi khác. Đây là một canh bạc hẹp hơn so với “tất cả sẽ hội tụ về một tệp”, và cũng phòng thủ hơn: nó không đòi hỏi mười sáu nền tảng còn lại phải áp dụng bất cứ điều gì mới thì AgentKits mới hoạt động đúng trên chúng ngay hôm nay.

Sự đánh đổi này thể hiện rõ ở những gì mỗi nền tảng được phép nhận. Chỉ có mục Claude Code có cả ba cờ skills: true, memory: true, và journeys: true. Mọi nền tảng khác, dù có ghi ra AGENTS.md hay không, đều bị giới hạn ở agent và lệnh. Những phần phong phú hơn của bộ công cụ vẫn ở lại riêng cho Claude Code; mọi đích khác nhận được một bản cài đặt vẫn hoạt động nhưng nông hơn — một cách có chủ đích, không phải do sơ suất.

Điều nghịch lý đáng được nhắc đến

Chính repo của AgentKits lại không có tệp AGENTS.md nào. Dự án này được phát triển chủ yếu bằng Claude Code, nên CLAUDE.md và thư mục .claude/ mới là nguồn gốc chuẩn của chính nó — cùng một thư mục mà trình cài đặt coi là chuẩn cho dự án của người khác. Vấn đề phân mảnh mà cả hệ sinh thái vẫn đang đàm phán để tìm chuẩn chung, bên trong chính codebase này, lại được giải quyết bằng cách không cần một tệp phổ quát cho công cụ đang thực sự xây dựng nên nó — và bằng cách tạo ra bất kỳ định dạng tệp nào mà công cụ của người dùng cuối cùng cần đến.

---

AgentKits là mã nguồn mở, miễn phí vĩnh viễn theo giấy phép MIT. Khám phá Marketing Kit, cài đặt vào dự án của riêng bạn, hoặc theo dõi những gì sắp tới tại agentkits.net, hoặc liên hệ chúng tôi qua hello@aitytech.com.