跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt

Use this file to discover all available pages before exploring further.

AGENTS.md 文件提供了一种简单的方法，可根据文件在项目中的位置，向 Cascade 提供具备上下文感知能力的指示，并自动生效。这对于提供特定目录的编码指南、架构决策或项目规范尤其有用。

​
工作原理

当你创建 AGENTS.md 文件 (或 agents.md) 时，Devin Desktop 会自动识别它，并将其接入与 .windsurf/rules/ 相同的规则引擎——不同之处在于，激活模式不是由 frontmatter 指定，而是根据文件位置推断：
  • 根目录：视为始终生效规则——完整内容会在每条消息中都包含在 Cascade 的系统提示中。
  • 子目录：视为 glob 规则，并自动生成模式 <directory>/** ——只有当 Cascade 读取或编辑该目录中的文件时，才会应用这些内容。
这种基于位置的作用域方式使 AGENTS.md 非常适合提供有针对性的指导，而不会让单一的全局配置文件变得杂乱。

​
创建 AGENTS.md 文件

只需在目标目录中创建一个名为 AGENTS.md 或 agents.md 的文件即可。该文件采用普通 Markdown 格式，无需任何特殊 frontmatter。

​
结构示例

my-project/
├── AGENTS.md                    # 适用于整个项目的全局指示
├── frontend/
│   ├── AGENTS.md                # 针对前端代码的指示
│   └── src/
│       └── components/
│           └── AGENTS.md        # 针对组件的指示
├── backend/
│   └── AGENTS.md                # 针对后端代码的指示
└── docs/
    └── AGENTS.md                # 适用于文档的指示

​
示例内容

以下是一个适用于 React 组件目录的 AGENTS.md 文件示例： 
# 组件规范

在此目录中使用组件时：

- 使用带钩子的函数式组件
- 遵循命名规范：组件使用 ComponentName.tsx，钩子使用 useHookName.ts
- 每个组件应有对应的测试文件：ComponentName.test.tsx
- 使用 CSS 模块进行样式设置：ComponentName.module.css
- 以具名导出方式导出组件，而非默认导出

## 文件结构

每个组件文件夹应包含：
- 主组件文件
- 测试文件
- 样式文件（如需要）
- 用于重新导出的 index.ts

​
发现与作用域

Devin Desktop 会自动发现你工作区各处的 AGENTS.md 文件：
  • 工作区扫描：会发现你工作区及其子目录中的所有 AGENTS.md 文件
  • Git 代码仓库支持：对于 git 代码仓库，Devin Desktop 还会向上搜索父级目录，直到 git 根目录
  • 不区分大小写：AGENTS.md 和 agents.md 都会被识别

​
自动确定作用域

AGENTS.md 的一个主要优势是可以根据文件位置自动确定作用域：
文件位置作用域
工作区根目录适用于所有文件 (始终启用)
/frontend/处理 /frontend/** 中的文件时适用
/frontend/components/处理 /frontend/components/** 中的文件时适用
这意味着你可以在不同层级设置多个 AGENTS.md 文件，每个文件都会为其对应目录提供更具体的指导。

​
最佳实践

为了充分发挥 AGENTS.md 文件的作用：
  • 保持指示聚焦：每个 AGENTS.md 都应包含与其所在目录用途相关的指示
  • 使用清晰的格式：项目符号、标题和代码块能让 Cascade 更容易遵循这些指示
  • 具体明确：具体示例和明确的规范比含糊的指导原则效果更好
  • 避免冗余：不要在子目录文件中重复全局指示；子目录会继承父目录中的内容

​
内容规范

# Good Example
- Use TypeScript strict mode
- All API responses must include error handling
- Follow REST naming conventions for endpoints

# Less Effective Example
- Write good code
- Be careful with errors
- Use best practices

​
与 Rules 的比较

虽然 AGENTS.md 和 Rules 都会向 Cascade 提供指示，但它们的用途不同：
功能AGENTS.mdRules
位置项目目录中.windsurf/rules/ 或全局
作用域根据文件位置自动确定手动 (glob、始终启用、模型决定、手动)
格式纯 Markdown带 frontmatter 的 Markdown
最适合目录级规范全局性关注点、复杂的激活逻辑
当你需要简单、基于位置的指示时，请使用 AGENTS.md。当你需要更精细地控制指示在何时以及如何应用时，请使用 Rules。