AGENTS.md
来源: https://agents.md/ 抓取时间: 2026-07-21 16:21:33
AGENTS.md
一个简单、开放的格式，用于指导编码智能体， 被超过 60,000 个开源项目 使用。 可以将 AGENTS.md 视为智能体的 README：一个专门、可预测的位置，用于提供上下文和指令来帮助 AI 编码智能体在你的项目中工作。 探索示例在 GitHub 上查看
AGENTS.md
设置命令
- 安装依赖：
pnpm install - 启动开发服务器：
pnpm dev - 运行测试：
pnpm test
代码风格
- TypeScript 严格模式
- 单引号，无分号
- 尽可能使用函数式模式
为什么选择 AGENTS.md？
README.md 文件是为人类准备的：快速入门、项目描述和贡献指南。 AGENTS.md 通过包含编码智能体所需的额外、有时详细的上下文来补充这一点：构建步骤、测试和约定，这些可能会使 README 变得混乱或与人类贡献者无关。 我们有意将其分开是为了： 为智能体提供清晰、可预测的指令位置。 保持 README 简洁，专注于人类贡献者。 提供精确的、以智能体为中心的指导，补充现有的 README 和文档。 我们没有引入另一个专有文件，而是选择了一个对任何人都有效的名称和格式。如果你正在构建或使用编码智能体并发现这很有帮助，请随意采用它。
一个 AGENTS.md 可以在许多智能体中使用
你的智能体定义与不断增长的 AI 编码智能体和工具生态系统兼容： OpenAI 的 Codex Google 的 Jules Factory Aider goose opencode Zed Warp VS Code](https://code.visualstudio.com/docs/editor/artificial-intelligence) Cognition 的 Devin UiPath 的 Autopilot & Coded Agents JetBrains 的 Junie Amp Cursor RooCode Google 的 Gemini CLI Kilo Code Phoenix Semgrep GitHub Copilot 的编码智能体 Ona Cognition 的 Windsurf Augment Code 查看所有支持的智能体
示例
示例 AGENTS.md 文件
开发环境提示
- 使用
pnpm dlx turbo run where <project_name>跳转到包，而不是用ls扫描。 - 运行
pnpm install --filter <project_name>将包添加到你的工作区，这样 Vite、ESLint 和 TypeScript 可以看到它。 - 使用
pnpm create vite@latest <project_name> -- --template react-ts快速创建一个新的 React + Vite 包，并准备好 TypeScript 检查。 - 检查每个包的 package.json 中的 name 字段以确认正确的名称——跳过顶层的。
测试说明
- 在 .github/workflows 文件夹中找到 CI 计划。
- 运行
pnpm turbo run test --filter <project_name>来运行为该包定义的每个检查。 - 从包根目录你可以直接调用
pnpm test。合并前提交应该通过所有测试。 - 要专注于一个步骤，添加 Vitest 模式：
pnpm vitest run -t "<test name>" - 修复任何测试或类型错误，直到整个套件变成绿色。
- 移动文件或更改导入后，运行
pnpm lint --filter <project_name>以确保 ESLint 和 TypeScript 规则仍然通过。 - 为你更改的代码添加或更新测试，即使没有人要求。
PR 说明
- 标题格式：[<project_name>] <Title>
- 提交前始终运行
pnpm lint和pnpm test。
openai/codex 用于 AI 编码智能体的通用 CLI 工具。Rust
apache/airflow 用于以编程方式创建、调度和监控工作流的平台。Python
temporalio/sdk-java Temporal 的 Java SDK，用代码定义的工作流编排。Java
PlutoLang/Pluto Lua 5.4 的超集，专注于通用编程。C++
如何使用 AGENTS.md？
1. 添加 AGENTS.md
在存储库根目录创建一个 AGENTS.md 文件。如果你友好地询问，大多数编码智能体甚至可以为你搭建一个。
2. 涵盖重要内容
添加帮助智能体有效处理你的项目的部分。热门选择：
- 项目概述
- 构建和测试命令
- 代码风格指南
- 测试说明
- 安全注意事项
3. 添加额外指令
提交消息或拉取请求指南、安全陷阱、大型数据集、部署步骤：你会告诉新团队成员的任何内容也都属于这里。
4. 大型 monorepo？为子项目使用嵌套的 AGENTS.md 文件
在每个包中放置另一个 AGENTS.md。智能体会自动读取目录树中最近的文件，因此最接近的文件具有优先权，每个子项目都可以提供量身定制的指令。例如，在撰写本文时，OpenAI 的主存储库有 88 个 AGENTS.md 文件。
关于
AGENTS.md 源自整个 AI 软件开发生态系统的协作努力，包括 OpenAI Codex、Amp、Google 的 Jules、Cursor 和 Factory。 我们致力于帮助维护和发展这个作为开放格式的项目，使整个开发者社区受益，无论你使用哪种编码智能体。 AGENTS.md 现在由 Linux 基金会下的 Agentic AI 基金会 管理。了解更多 →
常见问题
有必填字段吗？
没有。AGENTS.md 只是标准 Markdown。使用你喜欢的任何标题；智能体只会解析你提供的文本。
如果指令冲突怎么办？
离编辑文件最近的 AGENTS.md 获胜；明确的用户聊天提示会覆盖所有内容。
智能体会自动运行在 AGENTS.md 中找到的测试命令吗？
是的——如果你列出了它们。智能体会尝试执行相关的程序化检查，并在完成任务之前修复失败。
我可以稍后更新它吗？
当然可以。将 AGENTS.md 视为活的文档。
如何将现有文档迁移到 AGENTS.md？
将现有文件重命名为 AGENTS.md 并创建符号链接以保持向后兼容性：
mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
如何配置 Aider？
在 .aider.conf.yml 中配置 Aider 以使用 AGENTS.md：
read: AGENTS.md
如何配置 Gemini CLI？
在 .gemini/settings.json 中配置 Gemini CLI 以使用 AGENTS.md：
{ "context": { "fileName": "AGENTS.md" }, }