从 AGENTS.md 开始:构建 Agent 友好项目的五个步骤

从 AGENTS.md 开始:构建 Agent 友好项目的五个步骤

💡 原文中文,约4100字,阅读约需10分钟。
📝

内容提要

文章主张让Coding Agent真正融入项目工程化:先用AGENTS.md写清入口、命令与风险边界,再链接架构等核心文档形成知识路由;将重复流程沉淀为Skill,执行能力优先用CLI,必要时再接MCP,并用测试、Hook和权限守住边界;最终通过Agent Work Loop持续验证交付,把每次任务经验沉淀下来,帮助下一次任务。

🔎

延伸解读

先写入口,再谈工具

文章强调 AGENTS.md 应优先写清安装、测试命令、不可修改目录和安全边界,而不是堆砌架构细节。这提示读者:Agent 工程化的第一步不是接入更多工具,而是把项目里“看不出来却容易猜错”的事实显性化。根目录保持简短,详细内容通过链接按需读取,能避免文档膨胀后反而失效。

Skill 不是配置越多越好

文章给出 Skill 的创建门槛:相似需求至少出现两次,或单次成本高、风险大且可能复发,并确认输入稳定、步骤可复用、结果可检查。这提醒团队不要为每个偶发任务建 Skill,而应从最近几次对话中反复出现的摩擦入手。Skill 固定的是方法,不是替代文档或脚本。

CLI 优先,MCP 按需接入

对于已有脚本或命令行工具的项目,文章建议先把 CLI 整理成稳定接口,再考虑 MCP。原因是 CLI 成本低、易复现,能同时服务开发者、Agent、脚本和 CI。MCP 更适合缺少命令行入口或需要结构化资源发现的场景。关键不是工具数量,而是 CLI 与 MCP 共享同一套底层能力和权限规则。

用 Work Loop 检验实践是否生效

文章把从理解需求到验证交付称为 Agent Work Loop,并强调交付后要回看:Agent 是否重复寻找启动命令、是否在同一目录再犯错、是否仍需人提醒检查。写进仓库不等于生效,只有下一次类似任务中 Agent 能找到并用上,才说明这项实践值得保留。持续改进是让本次经验帮助下一次,而非不断增加配置。

❓

Q&A

AGENTS.md 应该写哪些内容?

AGENTS.md 应写清项目入口、安装与测试命令、无法从目录结构推断的约定、生成文件位置,以及涉及凭据、数据库迁移和发布的安全边界。内容要简短、准确、可执行,并采用渐进式披露:根目录只保留多数任务需要的说明,详细架构等通过链接按需读取。

如何让核心文档在 Agent 执行任务时被找到?

在 AGENTS.md 中不仅放链接,还要给出读取条件,例如“修改模块边界前:阅读 docs/ARCHITECTURE.md”,形成知识路由。同时确保同一事实只有一个权威来源,架构约束属于架构文档,AGENTS.md 只负责导航。

什么时候应该把重复流程沉淀为 Skill?

当相似需求至少出现过两次,或虽然只发生一次但成本高、风险大且很可能再次发生时,可考虑创建 Skill。还需确认输入相对稳定、步骤可复用、结果可检查,且未被现有文档、脚本或 Skill 覆盖。

为什么优先用 CLI 而不是 MCP?

对于已有脚本或命令行工具的项目,CLI 成本最低、最容易复现,能同时服务开发者、Agent、脚本和 CI。MCP 适合外部系统缺少命令行入口,或需要结构化资源发现、宿主集成、持续交互的场景。关键是让 CLI 与 MCP 建立在同一套底层能力和权限规则上。

如何确保 Agent 的修改结果被正确验证和交付?

Agent 完成修改、测试通过后,不要立即结束。应打开最终代码变更,确认测试覆盖的是修改后的版本,检查是否走完必要的 Review 和 CI。代码写完只是过程的一部分,结果能被验证和交付,任务才算完成。

Agent Work Loop 是什么?包含哪些环节?

Agent Work Loop 是从理解需求、找到知识、执行修改到验证交付的循环过程。其中 AGENTS.md 帮助 Agent 进入项目,核心文档提供上下文,Skill 与工具推动任务执行,测试、Hook 和权限守住结果与边界。

🏷️

标签

➡️

继续阅读