← 返回博客

AGENTS.md 与 CLAUDE.md：AI 编程智能体的新版 README

· Save Team
markdownaiagents-mdclaude-mdcodingdeveloper-tools

如果你最近使用过 AI 编程助手，你可能注意到了一件事：它们都需要一个 Markdown 文件。

GitHub Copilot 读取 .github/copilot-instructions.md，Cursor 读取 .cursor/rules/，Claude Code 读取 CLAUDE.md，Windsurf 读取 .windsurf/rules，Google 的 Jules 读取 JULES.md。而通用标准？AGENTS.md —— 现在已被超过 6 万个开源仓库使用，由 Linux 基金会的 Agentic AI Foundation 管理。

Markdown 已从文档格式演变为 AI 编程智能体的操作系统。

什么是 AGENTS.md？

AGENTS.md 是一个简单的开放格式 Markdown 文件，位于你的代码仓库中，作为 AI 编程智能体的简报包。可以将其视为 README.md 的对应物：

  • README.md 是给人类的：快速入门、项目描述、徽章
  • AGENTS.md 是给 AI 智能体的：构建步骤、测试命令、编码约定、架构决策

智能体读取目录树中最近的文件，所以最近的文件优先级最高。每个子项目都可以附带定制化的指令。

什么是 CLAUDE.md？

CLAUDE.md 专门用于 Anthropic 的 Claude Code。它在每次会话开始时自动读取，包含你否则需要在每个提示中重复的项目特定指令。

一个好的 CLAUDE.md 通常包括：

  • 项目背景：一句话让 Claude 了解项目是做什么的
  • 代码风格：你的格式偏好、命名约定、需要遵循的模式
  • 命令：如何运行测试、构建、lint 和部署
  • 架构说明：Claude 应该遵守的关键决策

推荐的做法：将共享指令放在 AGENTS.md 中（让所有 AI 工具受益），然后在 CLAUDE.md 中添加 Claude 特有的功能。

AI 指令文件的完整版图

以下是每个主要 AI 编程工具及其 Markdown 约定：

工具文件格式
GitHub Copilot.github/copilot-instructions.mdMarkdown
Cursor.cursor/rules/*.mdMarkdown
Claude CodeCLAUDE.mdMarkdown
Windsurf.windsurf/rulesMarkdown
Google JulesJULES.mdMarkdown
通用AGENTS.mdMarkdown

注意规律了吗？全都是 Markdown，无一例外。

为什么 Markdown 胜出

Markdown 是 AI 指令文件的完美格式，因为：

  1. LLM 原生理解 —— 它是训练数据中最常见的格式
  2. 人类可读 —— 开发者可以轻松审查和编辑指令
  3. 可版本控制 —— 与代码一起存放在 git 中
  4. 轻量级 —— 无解析开销，无需特殊工具
  5. 通用性 —— 适用于每个 AI 工具、编辑器和平台

正如 Visual Studio Magazine 所说：在智能体 AI 中，一切都与 Markdown 有关。

编写智能体指令的最佳实践

基于对数千个代码仓库的分析：

从简单开始。 只在你注意到智能体反复犯同样错误时才添加规则。过于详细的指令可能适得其反。

对命令要具体。 不要说「运行测试」——要说 pnpm test 或 pytest -x tests/。

记录你的架构。 如果你的项目使用特定模式（比如内容脚本和 service worker 之间的消息传递），请解释清楚。智能体无法仅从代码推断架构决策。

包含不该做什么。 负面指令出奇地有效：「永远不要直接修改数据库 schema」或「不要使用类组件，始终使用 hooks」。

Save 如何融入这个生态

如果你在构建智能体指令文件，你可能也在从网络保存参考资料：文档页面、Stack Overflow 答案、GitHub README、API 参考。

Save 只需一键即可将这些网络资料转换为干净的 Markdown —— 非常适合构建 AI 智能体所需的上下文。保存一个文档页面，将 Markdown 粘贴到 AGENTS.md 或参考文档中，你的 AI 编程助手立即获得了所需的上下文。

工作流：

  1. 在网络上找到有用的文档或代码示例
  2. 点击 Save 转换为 Markdown
  3. 在智能体指令文件中引用或包含
  4. 你的 AI 编程助手随着每次保存变得更强大

未来：Markdown 作为 AI 的控制界面

微软和 GitHub 现在将 Markdown 视为 AI 行为的稳定、可审计的控制界面。它不再只是文档——它是人类意图与 AI 执行之间的接口。

我们看到 Markdown 文件扮演着三个不同的角色：

  1. 文档：向人类解释系统
  2. 指令：约束和引导 AI 行为
  3. 技能：将指令与资源捆绑，使智能体可以重复工作流

这一趋势只会加速。随着 AI 编程助手能力不断增强，引导它们的 Markdown 文件变得越来越重要。

Save 只需一键即可将任何网页转换为干净的 Markdown。非常适合构建参考资料库、捕获文档和为 AI 编程工作流创建上下文。免费试用 Save。