> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS.md

> 创建 AGENTS.md 文件，为 Cascade 提供针对目录的指示。这些指示会根据文件在项目中的位置自动生效。

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

<div id="how-it-works">
  ## 工作原理
</div>

当你创建 `AGENTS.md` 文件 (或 `agents.md`) 时，Devin Desktop 会自动识别它，并将其接入支持 `.devin/rules/` (以及旧版 `.windsurf/rules/`) 的同一个[规则](/zh/desktop/cascade/memories#rules)引擎——不同之处在于，激活模式不是由 frontmatter 指定，而是根据文件位置推断：

* **根目录**：视为**始终生效**规则——完整内容会在每条消息中都包含在 Cascade 的系统提示中。
* **子目录**：视为 **glob** 规则，并自动生成模式 `<directory>/**` ——只有当 Cascade 读取或编辑该目录中的文件时，才会应用这些内容。

这种基于位置的作用域方式使 `AGENTS.md` 非常适合提供有针对性的指导，而不会让单一的全局配置文件变得杂乱。

<div id="creating-an-agentsmd-file">
  ## 创建 AGENTS.md 文件
</div>

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

<div id="example-structure">
  ### 结构示例
</div>

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

<div id="example-content">
  ### 示例内容
</div>

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

```markdown theme={null}
# 组件规范

在此目录中使用组件时：

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

## 文件结构

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

<div id="discovery-and-scoping">
  ## 发现与作用域
</div>

Devin Desktop 会自动发现你工作区各处的 `AGENTS.md` 文件：

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

<div id="automatic-scoping">
  ### 自动确定作用域
</div>

`AGENTS.md` 的一个主要优势是可以根据文件位置自动确定作用域：

| 文件位置                    | 作用域                                  |
| ----------------------- | ------------------------------------ |
| 工作区根目录                  | 适用于所有文件 (始终启用)                       |
| `/frontend/`            | 处理 `/frontend/**` 中的文件时适用            |
| `/frontend/components/` | 处理 `/frontend/components/**` 中的文件时适用 |

这意味着你可以在不同层级设置多个 `AGENTS.md` 文件，每个文件都会为其对应目录提供更具体的指导。

<div id="best-practices">
  ## 最佳实践
</div>

为了充分发挥 `AGENTS.md` 文件的作用：

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

<div id="content-guidelines">
  ### 内容规范
</div>

```markdown theme={null}
# 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
```

<div id="comparison-with-rules">
  ## 与规则的比较
</div>

虽然 `AGENTS.md` 和 [规则](/zh/desktop/cascade/memories#rules) 都会向 Cascade 提供指示，但它们的用途不同：

| 功能  | AGENTS.md  | 规则                                           |
| --- | ---------- | -------------------------------------------- |
| 位置  | 项目目录中      | `.devin/rules/` (或旧版 `.windsurf/rules/`) 或全局 |
| 作用域 | 根据文件位置自动确定 | 手动 (glob、始终启用、模型决定、手动)                       |
| 格式  | 纯 Markdown | 带 frontmatter 的 Markdown                     |
| 最适合 | 目录级规范      | 全局性关注点、复杂的激活逻辑                               |

当你需要简单、基于位置的指示时，请使用 `AGENTS.md`。当你需要更精细地控制指示在何时以及如何应用时，请使用规则。