AGENTS.md

定义

放置在仓库根目录或模块目录的项目级 Agent 指令文件——告诉编码 Agent 这个仓库/模块的导航地图、工作流、决策规则、复用模式。是 Claude Code（CLAUDE.md）、OpenAI Codex、Augment 等多家工具共享的事实标准格式。

要点

• 被 Agent 发现的概率接近 100%（孤立 _docs/ 文档低于 10%）——是最可靠的入口
• 不是越详细越好，理想长度 100–150 行 + 几份参考文档
• 不是 README 的复制——README 写给人，AGENTS.md 写给 Agent，需要砍掉所有"供人类扫读"内容
• 描述现状不是愿景——写代码库里还不存在的模式会让 Agent 误导
• 单文件引用不超过 10–15 个，否则上下文加载过重
• Agent 也通过 grep 和语义搜索发现资料，AGENTS.md 不是唯一入口但最可靠

六个有效模式

详见 AGENTS.md 写作六规律〔待补〕：渐进披露 / 步骤化工作流 / 决策表 / 真实代码片段 / 领域特定规则 / 禁止配替代。

失败模式

• 架构总览太多 → Agent 一路追文档，上下文爆炸（Context Rot）
• "别做"清单太长 → Agent 逐条核查不相关场景

相关概念

• Claude Code 的 .claude 文件夹结构〔待补〕
• Context Rot
• 渐进式披露
• 禁止配替代模式
• 决策表（Agent文档）

参考资料

• AGENTS.md 写作六规律〔待补〕
• Augment Code 与 AuggieBench 评测