拥抱智能协作：用AGENTS.md打造Agent友好型项目

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

在AI辅助编程已成为常态的今天，我们面对一个核心问题：如何让AI Agent（如GitHub Copilot、Cursor或各类自定义Agent）更高效、更精准地为我们工作？答案或许就藏在项目根目录下一个看似简单的文件中——AGENTS.md。

最近，我在重新整理 Better Harness 项目的 references 时，深刻体会到：一个对Agent友好的项目，其起点正是这份面向Agent的“操作手册”。它就像我们团队的新人指南，能帮助AI快速理解项目上下文、遵循团队规范，从而减少“幻觉”和无效输出。

本文将分享五个具体步骤，助你从零开始，构建一个Agent协作更顺畅的项目。

步骤一：创建入口，明确告知Agent“从这里读起”

在项目根目录下创建一个名为 AGENTS.md 的文件。这是Agent探索项目的首要线索。在其中用简洁的语言说明：“你好，Agent！本文件是你理解项目的核心入口。”

清晰的入口能避免Agent在庞大的代码库中盲目搜索，节省宝贵的上下文窗口。这体现了 SDD 文档驱动开发实战 中的核心理念：让文档成为沟通的枢纽，无论是人与人，还是人与AI。

步骤二：定义角色与规范，划定协作边界

在 AGENTS.md 中，你需要清晰地定义Agent的角色和必须遵守的规则。例如：

• 角色定位：“你是一位资深的全栈工程师，专注于代码重构和单元测试编写。”
• 技术栈：“项目使用React 18, TypeScript, 和 PostgreSQL。”
• 编码规范：“所有代码必须通过ESLint检查，并遵循Airbnb风格指南。”
• 禁止事项：“请勿修改database/config.ts中的生产环境配置，除非明确指示。”

这些规范为Agent设定了清晰的轨道，确保其产出符合项目质量要求。

步骤三：提供“地图”与“字典”，加速上下文理解

为Agent提供项目的关键结构图和核心术语表，能极大提升其理解速度。

1. 架构概览：简要描述主要模块、数据流和服务依赖关系。可以链接到已有的架构文档。
2. 核心概念：列出项目特有的术语和含义。例如，“Harness” 在本项目中特指“测试与部署编排器”。
3. 关键文件说明：指出哪些文件是配置枢纽、哪些是类型定义中心、哪些包含业务核心逻辑。

这相当于给了Agent一张地图，让它知道哪里是“市中心”，哪里是“功能区”。

步骤四：示例引导，用“样本”教会Agent沟通方式

与其用大量抽象规则，不如提供几个具体的交互范例。在 AGENTS.md 中设立一个“示例”部分：

好的提问方式：

“请为src/utils/date.ts中的formatToUTC函数补充JSDoc注释，并添加一个针对闰年的边界测试用例。”

避免的提问方式：

“改进代码。”

通过正反示例，Agent能更直观地学会如何进行有效、具体的协作。这类似于我们训练新人，提供模板远比空谈理论有效。

步骤五：测试与迭代，让文档保持“活性”

项目在演进，Agent的能力也在升级。AGENTS.md 不应是一次性文档。你需要：

• 定期审查：随着项目迭代，更新技术栈、规范等信息。
• 测试协作效果：通过实际任务，观察Agent是否遵循了文档指引。如果发现它频繁犯错，很可能是文档描述得不够清晰或已过时。
• 纳入版本控制：将 AGENTS.md 的变更与代码变更同等对待，通过PR进行评审和更新。

将文档维护流程化，才能确保其持续有效，真正成为驱动高效协作的活文档。

结语：迈向人机协作的未来工作流

当我们思考 超级能力而非超级智能：AI发展的务实路径 时，会发现提升工具的“可用性”与提升其“智能”同等重要。编写 AGENTS.md 正是这样一种务实且高效的实践——它不追求AGI的复杂性，而是专注于通过结构化沟通，极大增强现有AI工具的实用效能。

从今天开始，为你最重要的项目创建一个 AGENTS.md 吧。这是向更高效、更可预测的智能协作未来迈出的一小步，却可能是提升你团队生产力的一大步。当你习惯了与Agent进行如此清晰的对话，再回过头处理 Text2SQL ：用自然语言操作 SQLite 数据库 这类特定任务时，你会发现一切障碍都已扫清。