前置条件
- 1已安装至少一个支持 AGENTS.md 的 AI 编程客户端（Claude Code 2.1.277+ / Codex CLI / Cursor / Trae）
- 2有一个实际的 Git 仓库用于实践
- 3了解基本的 Markdown 语法
腾讯智能体开发平台 ADP
新客首月专属价，最高直降 880 元，构建/分发/治理企业级 Agent
常见问题
QAGENTS.md 和 CLAUDE.md 到底留哪个？
新项目只留 AGENTS.md，它是跨工具规范，Claude Code 2.1.277+ 已经原生支持回退读取。已有 CLAUDE.md 的老项目，如果只用 Claude Code 可以不迁；一旦引入第二个工具（Codex / Cursor / Trae），就必须合并成 AGENTS.md，否则两套配置会打架——不同工具读到不同规范，行为不一致且极难排查。
Q子目录里的 AGENTS.md 会覆盖根目录的吗？
不会覆盖，是就近追加。客户端会把从仓库根到当前工作目录路径上的所有 AGENTS.md 全部拼接起来，越靠近当前文件的优先级越高。所以根目录只写全局约定（技术栈、编码规范、禁区），子目录只写该模块的特殊约定。别在子目录重复根目录内容，会白白吃掉上下文。
QAGENTS.md 写多长合适？
根目录控制在 150 行以内，全文不超过 400 行。它每次会话都会被注入上下文，写长了等于长期缴一笔上下文税。实测一个 900 行的 AGENTS.md 会让每次请求多花 12K tokens，一个月下来在多 Agent 场景下是实打实的成本。把细节挪到 docs/ 里，用链接指过去，让 Agent 按需读取。
QCursor 和 Trae 真的读 AGENTS.md 吗？
读，但支持程度不同。Cursor 从 2025 年底开始支持项目根 AGENTS.md；Trae 在 2026 年跟进。两者都不支持子目录就近覆盖（只有根目录那份生效），且对 @引用 语法支持不完整。本文第 4 节给了完整的兼容矩阵，照着写就能四个工具都跑通。