> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/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`) 时，Windsurf 会自动发现它，并将其接入驱动 `.windsurf/rules/` 的同一个 [Rules](/zh/windsurf/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}
# Component Guidelines

When working with components in this directory:

- Use functional components with hooks
- Follow the naming convention: ComponentName.tsx for components, useHookName.ts for hooks
- Each component should have a corresponding test file: ComponentName.test.tsx
- Use CSS modules for styling: ComponentName.module.css
- Export components as named exports, not default exports

## File Structure

Each component folder should contain:
- The main component file
- A test file
- A styles file (if needed)
- An index.ts for re-exports
```

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

Windsurf 会在你的工作区中自动发现 `AGENTS.md` 文件：

* **工作区扫描**：会发现你工作区及其子目录中的所有 `AGENTS.md` 文件
* **Git 仓库支持**：对于 Git 仓库，Windsurf 还会向上搜索父目录，直到 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">
  ## 与 Rules 的比较
</div>

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

| 特性   | AGENTS.md  | Rules                           |
| ---- | ---------- | ------------------------------- |
| 位置   | 位于项目目录中    | `.windsurf/rules/` 或全局          |
| 作用范围 | 基于文件位置自动生效 | 手动配置 (glob、始终启用、由 AI 模型决定、手动触发) |
| 格式   | 纯 Markdown | 带 frontmatter 的 Markdown        |
| 最适合  | 针对目录的约定    | 横切关注点、复杂的激活逻辑                   |

当你只需要基于位置的简单指令时，使用 `AGENTS.md`。当你需要对指令何时以及如何生效有更多控制时，使用 Rules。