跳转到主要内容
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。

​
示例结构

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

​
示例内容

这是一个 React 组件目录的 AGENTS.md 示例文件： 
# 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

​
发现与作用域

Windsurf 会在你的工作区中自动发现 AGENTS.md 文件：
  • 工作区扫描：会发现你工作区及其子目录中的所有 AGENTS.md 文件
  • Git 仓库支持：对于 Git 仓库，Windsurf 还会向上搜索父目录，直到 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、始终启用、由 AI 模型决定、手动触发)
格式纯 Markdown带 frontmatter 的 Markdown
最适合针对目录的约定横切关注点、复杂的激活逻辑
当你只需要基于位置的简单指令时，使用 AGENTS.md。当你需要对指令何时以及如何生效有更多控制时，使用 Rules。