跳转到主要内容

AGENTS.md 文件

AGENTS.md 文件提供了一种标准化的方式来配置不同 AI 编码工具中的 AI 代理行为。它们允许您定义项目特定的指令、编码标准和指南，AI 代理在与您的代码库协作时应遵循这些内容。

什么是 AGENTS.md？​

AGENTS.md 是一个用于配置软件项目中 AI 代理行为的开放标准。它是一个放置在项目根目录的简单 Markdown 文件，包含给 AI 编码助手的指令。该标准被多个 AI 编码工具支持，包括 YouCode、Cursor 和 Windsurf。

可以将 AGENTS.md 理解为"AI 代理的 README"——它告诉 AI 如何与您的特定项目协作、遵循哪些约定以及遵守哪些约束。

为什么使用 AGENTS.md？​

  • 可移植性：可在多个 AI 编码工具中使用，无需修改
  • 版本控制：与代码一起存放在您的仓库中
  • 团队一致性：确保所有团队成员的 AI 助手遵循相同的指南
  • 项目特定：针对您项目的独特要求和约定进行定制
  • 简单格式：纯 Markdown——无需特殊语法或配置

文件位置和命名​

项目级 AGENTS.md​

将您的 AGENTS.md 文件放置在项目__根目录__：

my-project/
├── AGENTS.md          # 主要文件名（推荐）
├── src/
├── package.json
└── README.md

支持的文件名（按优先级排序）：

  1. AGENTS.md（大写，复数——推荐）
  2. AGENT.md（大写，单数——备选）
大小写敏感性

文件名必须是大写（AGENTS.md），而不是小写（agents.md）。这确保了不同操作系统和工具之间的一致性。

子目录 AGENTS.md 文件​

您也可以在子目录中放置 AGENTS.md 文件以提供特定于上下文的指令：

my-project/
├── AGENTS.md                    # 根级指令
├── src/
│   └── backend/
│       └── AGENTS.md            # 后端特定指令
└── docs/
    └── AGENTS.md                # 文档特定指令

在子目录中工作时，YouCode 将加载根 AGENTS.md 和任何子目录 AGENTS.md 文件，对于冲突的指令，子目录文件优先。

文件保护​

在 YouCode 中，AGENTS.md 和 AGENT.md 都是__写保护文件__。这意味着：

  • AI 代理未经您明确批准不能修改这些文件
  • 系统会提示您确认对这些文件的任何更改
  • 这可以防止对项目 AI 配置的意外修改

基本语法和结构​

AGENTS.md 文件使用标准 Markdown 语法。没有必需的结构，但使用标题和列表组织内容会使 AI 模型更容易解析和理解。

推荐结构​

# 项目名称

项目的简要描述和目的。

## 代码风格

- 所有新文件使用 TypeScript
- 遵循 ESLint 配置
- 使用 2 个空格缩进

## 架构

- 遵循 MVC 模式
- 保持组件在 200 行以下
- 使用依赖注入

## 测试

- 为所有业务逻辑编写单元测试
- 保持代码覆盖率 >80%
- 使用 Jest 进行测试

## 安全性

- 永远不要提交 API 密钥或秘密
- 验证所有用户输入
- 使用参数化查询进行数据库访问

最佳实践​

  • 具体明确：使用具体的规则，如"将圈复杂度限制在 < 10"，而不是像"编写好代码"这样的模糊指导
  • 包含代码示例：展示错误处理、命名约定或架构决策的模式
  • 按类别组织：在清晰的标题下组织相关指南（代码风格、架构、测试、安全性）
  • 保持简洁：使用项目符号和直接语言；避免冗长的段落
  • 定期更新：随着项目约定的变化定期审查和修订

AGENTS.md 在 YouCode 中的工作方式​

加载行为​

当您在 YouCode 中启动任务时：

  1. YouCode 检查项目根目录中的 AGENTS.md 或 AGENT.md
  2. 如果找到，内容将被加载并包含在 AI 的上下文中
  3. AI 在整个对话过程中遵循这些指令
  4. AGENTS.md 的更改在新任务中生效（可能需要重新加载）

与其他规则的交互​

AGENTS.md 与 YouCode 的其他配置系统协同工作：

功能范围位置目的优先级
模式特定自定义规则项目.youcode/rules-{mode}/模式特定规则和约束1（最高）
自定义规则项目.youcode/rules/YouCode 特定规则和约束2
AGENTS.md项目项目根目录或子文件夹跨工具标准的项目指南3
全局自定义规则全局~/.youcode/rules/全局 YouCode 规则4
自定义指令全局IDE 设置所有项目的个人偏好5（最低）

启用/禁用 AGENTS.md​

AGENTS.md 支持在 YouCode 中__默认启用__。要禁用它，请编辑 settings.json：

{
  "youcode.useAgentRules": false
}

外部资源​

相关功能​