Trình tạo AGENTS.md
Điền một biểu mẫu để tạo AGENTS.md với các lệnh, quy ước và giới hạn nghiêm ngặt của bạn. Bạn cũng sẽ nhận được một quy tắc theo đường dẫn cho Cursor, GitHub Copilot, Claude Code, Cline và Devin Desktop, cùng các tệp cầu nối dành cho những công cụ không tự động đọc AGENTS.md.
Vị trí lưu tệp hướng dẫn của từng công cụ →
# Ứng dụng web Acme
Ứng dụng web dành cho khách hàng, có khu vực quản trị và một REST API nhỏ.
## Stack
Next.js, React, TypeScript, pnpm
## Lệnh
- Cài đặt: `pnpm install`
- Chạy cục bộ: `pnpm dev`
- Kiểm thử: `pnpm test`
- Lint và kiểm tra kiểu: `pnpm lint && pnpm tsc --noEmit`
- Build: `pnpm build`
## Phong cách viết mã
- Tuân theo định dạng mà linter yêu cầu và giữ nguyên các tệp không cần chỉnh sửa.
- Ưu tiên các hàm nhỏ, có đầu vào và đầu ra rõ ràng; chỉ thực hiện side effect ở rìa hệ thống.
- Hỏi trước khi thêm dependency mới.
- Giải thích lý do đằng sau những đoạn code không hiển nhiên, không mô tả chức năng của từng dòng.
## Kiểm thử
- Thêm hoặc cập nhật kiểm thử cho mọi hành vi bạn thay đổi.
- Chạy lệnh kiểm thử và sửa mọi lỗi trước khi báo đã hoàn tất.
- Không xóa hoặc bỏ qua kiểm thử thất bại chỉ để toàn bộ bộ kiểm thử chạy thành công.
## Commit và pull request
- Viết tiêu đề commit ở thể mệnh lệnh, dưới 72 ký tự.
- Mỗi pull request chỉ nên bao gồm một thay đổi; nêu cách bạn kiểm thử thay đổi đó trong phần mô tả.
- Chạy lint và kiểm thử trước mỗi commit.
## Không bao giờ
- Không bao giờ commit secrets, API keys hoặc tệp .env.
- Không bao giờ chỉnh sửa thủ công các tệp được tạo trong src/generated/; hãy tạo lại chúng.
- Không bao giờ chạy các lệnh cơ sở dữ liệu có thể gây mất dữ liệu trên môi trường production.
- Không bao giờ force-push lên main hoặc viết lại lịch sử dùng chung.
Cùng một quy tắc cho năm công cụ
---
description: Quy ước cho các tệp khớp với glob này
globs: app/**/*.tsx
alwaysApply: false
---
Tuân theo các mẫu đã được dùng trong những tệp lân cận trong thư mục này. Mỗi hàm được export phải có docstring và một bài kiểm thử trong tệp kiểm thử tương ứng.
---
applyTo: "app/**/*.tsx"
---
Tuân theo các mẫu đã được dùng trong những tệp lân cận trong thư mục này. Mỗi hàm được export phải có docstring và một bài kiểm thử trong tệp kiểm thử tương ứng.
---
paths:
- "app/**/*.tsx"
---
Tuân theo các mẫu đã được dùng trong những tệp lân cận trong thư mục này. Mỗi hàm được export phải có docstring và một bài kiểm thử trong tệp kiểm thử tương ứng.
---
paths:
- "app/**/*.tsx"
---
Tuân theo các mẫu đã được dùng trong những tệp lân cận trong thư mục này. Mỗi hàm được export phải có docstring và một bài kiểm thử trong tệp kiểm thử tương ứng.
---
trigger: glob
globs: app/**/*.tsx
---
Tuân theo các mẫu đã được dùng trong những tệp lân cận trong thư mục này. Mỗi hàm được export phải có docstring và một bài kiểm thử trong tệp kiểm thử tương ứng.
Điều gì giúp tệp hướng dẫn phát huy hiệu quả
Đặt các lệnh chính xác ở gần đầu tệp
Liệt kê sớm trong tệp các lệnh cài đặt, kiểm thử và lint thực tế, kèm theo các flag. Nêu chính xác stack và phiên bản, đồng thời đưa ra một đoạn mã ngắn nếu diễn giải bằng văn bản có thể gây mơ hồ.
Viết rõ các quy tắc cấm
Nêu rõ những việc agent không được làm, chẳng hạn như truy cập secrets, mã được vendoring hoặc môi trường production. Không bao giờ commit secrets là ràng buộc hữu ích phổ biến nhất trong các tệp GitHub đã xem xét.
Đảm bảo từng chỉ dẫn có thể kiểm tra
Chạy npm test trước khi commit có thể kiểm tra được; hãy kiểm thử các thay đổi của bạn thì không. Xóa các mâu thuẫn, vì khi hai dòng không nhất quán, model có thể làm theo bất kỳ dòng nào.
Viết ngắn gọn và chia theo đường dẫn
Anthropic khuyến nghị mỗi tệp dưới 200 dòng, còn Cursor khuyến nghị mỗi rule dưới 500 dòng. Chuyển hướng dẫn cho một khu vực vào rule giới hạn theo đường dẫn để chỉ tải khi các tệp đó được xử lý. Dùng import giúp tệp gọn gàng hơn nhưng không giảm chi phí context.
Bỏ qua những điều agent đã biết
Trong nghiên cứu về bốn coding agent, các tệp context không giúp tăng tỷ lệ hoàn thành tác vụ một cách đáng tin cậy và làm chi phí suy luận tăng hơn 20%. Các tệp do LLM viết còn làm kết quả giảm nhẹ, còn phần tổng quan repository không giúp ích. Vì vậy, chỉ giữ lại các yêu cầu khó đoán, chẳng hạn như yêu cầu về tooling cụ thể.
Bổ sung rule khi lỗi lặp lại
Bắt đầu với ít rule và thêm một dòng khi thấy agent mắc cùng một lỗi nhiều hơn một lần. Dẫn chiếu đến tệp có sẵn làm mẫu thay vì dán cả hướng dẫn về style.
Câu hỏi về AGENTS.md
Claude Code có đọc AGENTS.md không?
Có, kể từ v2.1.277. Theo mặc định, Claude Code chỉ đọc AGENTS.md hoặc .claude/AGENTS.md khi trong thư mục làm việc hoặc các thư mục cha không có CLAUDE.md, .claude/CLAUDE.md hay CLAUDE.local.md. Cài đặt claude-md-and-agents-md sẽ tải cả hai, còn tệp CLAUDE.md có chứa @AGENTS.md sẽ hoạt động trên mọi phiên bản.
AGENTS.md có cần frontmatter hoặc các heading cụ thể không?
Không. AGENTS.md là Markdown thuần, không có trường bắt buộc và bạn có thể dùng heading tùy ý. Trang agents.md gợi ý các mục như tổng quan dự án, lệnh build và kiểm thử, phong cách viết mã, kiểm thử, lưu ý bảo mật và hướng dẫn pull request.
Làm thế nào để dùng AGENTS.md trong monorepo?
Đặt một tệp AGENTS.md ở thư mục gốc và một tệp khác trong mỗi package cần có rule riêng. Agent đọc tệp gần với mã đang được chỉnh sửa nhất; nếu có xung đột, tệp đó được ưu tiên. Khi agents.md ghi nhận điều này, repository chính của OpenAI có 88 tệp như vậy.
Làm thế nào để Gemini CLI đọc AGENTS.md?
Gemini CLI vẫn mặc định dùng GEMINI.md. Thêm AGENTS.md vào context.fileName trong .gemini/settings.json, ví dụ ["AGENTS.md", "GEMINI.md"]. Chạy /memory show để kiểm tra nội dung đã được tải.
Những coding agent nào hỗ trợ AGENTS.md?
Chúng tôi đã kiểm tra tài liệu của OpenAI Codex, Claude Code, Cursor, GitHub Copilot, Devin Desktop, Cline và OpenClaw; tất cả đều đọc định dạng này trực tiếp. Gemini CLI và Aider cần thêm một dòng cấu hình. Trang agents.md liệt kê tổng cộng 23 công cụ tương thích, trong đó có Zed, Warp, goose, opencode, Jules và JetBrains Junie.
Ai duy trì định dạng AGENTS.md?
OpenAI đã đóng góp AGENTS.md cho Agentic AI Foundation, một quỹ do Linux Foundation quản lý, được công bố vào 2025-12-09 cùng với MCP và goose. Trang agents.md cho biết hơn 60k dự án mã nguồn mở sử dụng định dạng này.