从 AGENTS.md 开始：构建 Agent 友好项目的五个步骤
内容提要
本文探讨如何让Coding Agent更有效地参与项目工程化。核心观点是，项目应通过AGENTS.md提供入口地图，用核心文档链接知识，用Skill沉淀重复流程，用CLI或MCP接入工具，并通过测试和权限验证结果。改进应基于真实任务中的摩擦，持续沉淀经验，使项目逐步拥有AI可用的工程能力。
延伸解读
渐进式披露：先建入口，再连知识
文章强调 AGENTS.md 应遵循渐进式披露原则，根目录只放多数任务必需的说明，详细架构通过链接按需读取。这避免了文档过载，让 Agent 能快速定位关键信息。实践中，应先写清入口、命令、风险和文档导航，再逐步补充细节，而不是一开始就追求完美手册。
沉淀 Skill 的门槛：重复与成本
并非所有重复流程都值得立即创建 Skill。文章提出两个门槛：相似需求至少出现两次，或虽只一次但成本高、风险大且可能再现。同时需确认输入稳定、步骤可复用、结果可检查，且未被现有文档或脚本覆盖。这有助于避免过度工程化，聚焦真正有价值的流程沉淀。
CLI 优先，MCP 按需
对于已有脚本或命令行工具的项目，CLI 是成本最低的起点，可同时服务开发者、Agent、脚本和 CI。当外部系统缺少命令行入口或需结构化交互时，才考虑 MCP。关键是让 CLI 与 MCP 建立在同一套底层能力和权限规则上，避免重复定义，确保职责清晰、过程可复现。
验证与沉淀：让经验进入下一次任务
任务完成后，应检查最终代码变更、测试覆盖和 CI 结果，确保结果可验证。同时回顾任务中的摩擦和有效经验，判断应沉淀到何处。写进仓库并不代表生效，只有下次任务能真正用上并减少返工，实践才有价值。持续改进不是增加配置，而是让经验真正帮助下一次。
Q&A
如何让 Coding Agent 更有效地参与项目工程化？
通过 AGENTS.md 提供项目入口地图，用核心文档链接知识，用 Skill 沉淀重复流程，用 CLI 或 MCP 接入工具，并通过测试和权限验证结果。改进应基于真实任务中的摩擦，持续沉淀经验。
AGENTS.md 文件应该包含哪些内容？
AGENTS.md 应包含项目使用的包管理器和运行时、安装与测试命令、无法从目录结构推断的约定、生成文件的位置，以及涉及凭据、数据库迁移和发布时的安全边界。应简短、准确、可执行，并遵循渐进式披露原则。
为什么 AGENTS.md 要遵循渐进式披露原则？
渐进式披露原则要求根目录只保留多数任务都需要的说明，更详细的架构、设计和工作流程通过链接按需读取。这样可以让 Agent 快速获取必要信息，避免信息过载，同时保持文档的准确性和可维护性。
如何让项目文档在任务进行时能被 Agent 找到？
在 AGENTS.md 中不仅列出文档链接，还要给出读取条件，例如“修改模块边界前阅读 docs/ARCHITECTURE.md”。同时确保同一事实只有一个权威来源，避免重复和过时信息。
什么情况下应该创建 Skill？
当相似需求至少出现过两次，或者虽然只发生过一次但成本高、风险大且很可能再次发生时，可以考虑创建 Skill。同时要确认输入相对稳定、步骤能够复用、结果可以检查，且没有被现有文档、脚本或 Skill 覆盖。
CLI 和 MCP 在 Agent 工具接入中分别适用什么场景？
CLI 适用于已有脚本或命令行工具的项目，成本低、易复现，可同时服务开发者、Agent、脚本和 CI。MCP 适用于外部系统缺少合适命令行入口，或需要结构化资源发现、宿主集成、持续交互的场景。两者应建立在同一套底层能力和权限规则上。
Agent 完成修改后，如何验证结果是否可靠？
打开最终代码变更，确认测试覆盖的是这次修改后的版本，再检查是否走完了必要的 Review 和 CI。代码写完只是过程的一部分，结果能够被验证和交付，任务才算完成。
如何持续改进 Agent 友好的项目？
在每次任务交付后，回顾 Agent 是否重新寻找命令、重复犯错或需要提醒，同时留意有效经验。将这些摩擦和有效经验沉淀到 AGENTS.md、Skill 或文档中，并在下次任务中验证其效果。
