AGENTS.md 文件提供了一种简单方式，可以为 Cascade 提供上下文感知的指令，并会根据文件在项目中的位置自动生效。这在为特定目录提供编码规范、架构决策或项目约定时尤其有用。
工作原理
AGENTS.md 文件 (或 agents.md) 时，Windsurf 会自动发现它，并将其接入驱动 .windsurf/rules/ 的同一个 Rules 引擎——只是激活模式不是由 frontmatter 决定，而是根据文件所在位置推断：
- 根目录：视为始终启用规则——其完整内容会在每条消息中都包含在 Cascade 的系统提示中。
- 子目录：视为 glob 规则，并自动生成
<directory>/**模式——只有当 Cascade 读取或编辑该目录内的文件时，内容才会生效。
AGENTS.md 非常适合提供有针对性的指导，而不会让单个全局配置文件显得臃肿。
创建 AGENTS.md 文件
AGENTS.md 或 agents.md 的文件即可。该文件使用普通 Markdown 格式，不需要任何特殊的 frontmatter。
示例结构
示例内容
AGENTS.md 示例文件：
发现与作用域
AGENTS.md 文件：
- 工作区扫描：会发现你工作区及其子目录中的所有
AGENTS.md文件 - Git 仓库支持：对于 Git 仓库，Windsurf 还会向上搜索父目录，直到 Git 根目录
- 不区分大小写：
AGENTS.md和agents.md都会被识别
自动作用域
AGENTS.md 的一大优势是可以根据文件位置自动确定作用域：
这意味着你可以在不同层级放置多个
AGENTS.md 文件，每个文件为其所在目录提供更细致、更加具体的指导。
最佳实践
AGENTS.md 文件：
- 保持说明重点明确：每个
AGENTS.md只应包含与其所在目录用途相关的说明 - 使用清晰的格式：项目符号、标题和代码块可以让 Cascade 更容易理解和执行这些说明
- 尽量具体：具体示例和明确约定比含糊的指导原则效果更好
- 避免冗余：不要在子目录文件中重复全局说明；它们会从父目录继承
内容指南
与 Rules 的比较
AGENTS.md 和 Rules 都会向 Cascade 提供指令，但它们的用途不同：
当你只需要基于位置的简单指令时，使用
AGENTS.md。当你需要对指令何时以及如何生效有更多控制时，使用 Rules。