---
title: "上下文、规则与 AGENTS.md"
description: "区分 Windsurf 上下文检索、Memories、Rules、AGENTS.md、Workflows、Skills 与忽略规则。"
verifiedAt: "2026-05-09"
---

Windsurf 的上下文治理有两件事：让 Cascade 能看到真正相关的代码和资料，同时阻止它把临时事实、团队规范、密钥路径、缓存目录和个人偏好混在一起。

官方 Memories & Rules 页面给出一个关键建议：如果希望 Cascade 稳定复用某条知识，优先写成 Rule 或加入仓库里的 `AGENTS.md`，不要只依赖自动生成的 Memories。再结合 Context Awareness、Fast Context、Remote Indexing 和 `.codeiumignore`，才能形成完整的上下文边界。

> [!TIP]
> **本章目标**：读完后，你应该能判断一条信息应该被索引、被 pin、写进 Memory、写成 Rule、放入 `AGENTS.md`、封装为 Workflow/Skill，还是加入 `.codeiumignore`。

## 1. 先分清两类上下文

Windsurf 的上下文可以分成“检索上下文”和“行为规则”。

| 类型 | 解决什么 | 典型机制 |
| --- | --- | --- |
| 检索上下文 | Cascade 需要知道哪些代码、文件、文档和仓库信息 | Context Awareness、Fast Context、Pinned context、Knowledge Base、Remote Indexing |
| 行为规则 | Cascade 应该如何行动、遵守哪些约束 | Memories、Rules、AGENTS.md、Workflows、Skills、system rules |

这两类不能混用。比如“这个目录是前端组件，只能改 TSX 和 CSS”属于行为规则；“这个组件依赖另一个包里的接口定义”属于检索上下文；“`.env` 不该被读取”属于索引和访问边界。

## 2. Context Awareness：默认会索引代码库

官方 Context Awareness 页面说明，Windsurf 采用 **RAG（Retrieval-Augmented Generation，检索增强生成）** 方式理解代码库——AI 不是凭脑子答，而是先从你的代码库里检索相关片段，再把这些片段拼成上下文交给模型。默认会考虑：

- 当前文件和其他打开文件。
- 本地代码库索引中的相关代码片段。
- Pro 用户的扩展上下文长度、更高索引限制、自定义上下文和 pinned context 限制。
- Teams / Enterprise 用户的远程仓库索引能力。

使用建议：

1. 当前任务依赖其他模块时，pin 最少必要文件或目录。
2. 不要一次 pin 太多；官方提醒过多 context 可能拖慢或降低模型表现。
3. 单测任务可以 pin 被测类或接口定义。
4. 内部框架、SDK 示例、`.proto`、抽象类、配置模板适合按任务 pin。
5. 一旦任务结束，及时清理不再需要的 pin。

## 3. Fast Context：让检索快，不是让权限变大

官方 Fast Context 页面说明，它是 Windsurf 内的 specialized subagent，用 SWE-grep / SWE-grep-mini 检索代码，目标是比传统 agentic search 更快地找到相关文件和片段。

它的几个事实边界：

- 当 Cascade 的问题需要代码搜索时自动触发。
- SWE-grep 负责复杂检索，SWE-grep-mini 负责更快检索。
- 官方描述 SWE-grep-mini serving speed 超过 2,800 tokens/s。
- 模型会在最多 4 turns 内，每 turn 最多执行 8 个并行 tool calls。
- 工具集受限于跨平台兼容的 grep、read、glob。

Fast Context 提升的是检索速度和相关性，不是安全授权。敏感目录仍然要靠 `.codeiumignore`、Rules、权限和人工边界控制。

## 4. Remote Indexing 和 Knowledge Base 的团队边界

官方 Remote Indexing 页面说明，Teams 和 Enterprise 可以把 GitHub、GitLab、BitBucket 仓库加入 Windsurf Indexing Service。索引和 embedding 在 Windsurf 服务器的 **isolated tenant**（独立租户——给每个团队分配的专属处理空间，团队之间数据互相隔离）中完成；如果 `Store Snippets` 未勾选，官方说明创建 embeddings 后会删除代码和代码片段，只保留 embeddings。

它适合：

- 团队跨多个仓库协作，但成员本地没有完整代码。
- 想让 Cascade 能引用共享仓库知识。
- 需要按组织集中管理索引。

它不适合：

- 未经授权索引客户私有仓库。
- 把数据隔离和访问控制完全交给工具默认值。
- 把远程索引当成代码审计或权限系统。

Knowledge Base 仍是 Beta，官方说明仅 Teams / Enterprise 可用，当前支持连接 Google Docs，最多添加 50 个 Google Docs 作为团队知识来源。关键风险是：如果 admin 把一个 Google Doc 加入团队知识源，团队用户都可访问该文档内容，不遵循 Google Drive 侧的个人访问控制。

> [!WARNING]
> 团队知识库不是“谁有 Google Doc 权限谁能看”。一旦 admin 加入 Windsurf Knowledge Base，就要按团队可见来处理。

## 5. Memories、Rules、AGENTS.md、Workflows、Skills

官方 Memories & Rules 页面把几种机制放在同一张选择表里。结合实操，可以这样判断：

| 机制 | 解决什么 | 如何激活 | 适合放什么 |
| --- | --- | --- | --- |
| Memories | Cascade 自动保存和检索会话中有用的事实 | 相关时自动检索 | 一次性背景、个人临时偏好、当前 workspace 状态 |
| Rules | 明确告诉 Cascade 怎么行动 | `always_on`、`glob`、`model_decision`、`manual` | 编码规范、项目约束、团队风格 |
| AGENTS.md | 按目录位置自动生效的规则 | root always-on，子目录自动 glob | 目录职责、架构约定、分层规范 |
| Workflows | 可重复多步 prompt 模板 | 手动 slash command | 发布、PR review、release checklist |
| Skills | 带脚本、模板、参考文件的复杂能力包 | 模型动态调用或 `@mention` | 需要材料、脚本和流程的复杂任务 |
| .codeiumignore | 控制不该被 Windsurf 读取、编辑或创建的路径 | gitignore-style pattern | 密钥、构建产物、大缓存、无关数据 |

这两类先做第一刀判断，再看是不是需要"封装成可重复流程"——后者会把内容从 Rule/AGENTS.md 升级为 Workflow 或 Skill：

```mermaid
flowchart TD
    Need["一条信息或约定"] --> NeedRead{"Cascade 需要读取它吗？"}
    NeedRead -->|不应读取| Ignore[".codeiumignore"]
    NeedRead -->|需要读取| Flow{"是要封装为可重复流程？"}
    Flow -->|纯 prompt 模板| Workflow["Workflow"]
    Flow -->|脚本/模板/参考文件| Skill["Skill"]
    Flow -->|不是流程，只是知识/约束| Durable{"团队要长期复用？"}
    Durable -->|否| Memory["Memory 或临时上下文"]
    Durable -->|是| Scoped{"按目录生效？"}
    Scoped -->|是| Agents["AGENTS.md"]
    Scoped -->|否| Rules["Rules"]

    style Agents fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style Rules fill:#e0f2fe,stroke:#0284c7,stroke-width:2px
    style Workflow fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Skill fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Ignore fill:#fee2e2,stroke:#dc2626,stroke-width:2px
```

## 6. Memories：本机、workspace、非团队规范

官方说明，Cascade 会自动生成 memories，也可以通过提示让它创建 memory。自动 memories 关联创建它们的 workspace，存储在本机：

```bash
~/.codeium/windsurf/memories/
```

某个 workspace 生成的 memories 不会在另一个 workspace 中可用，也不会提交到仓库；创建和使用自动 memories 不消耗 credits。

所以 Memories 不适合承载团队规范、架构约束、测试命令、发布流程或安全边界。需要稳定复用、团队共享、版本控制的内容，应放进 Rule、`AGENTS.md`、Workflow 或 Skill。

## 7. Rules：全局、workspace、system 三层

官方列出的 Rules 位置和限制如下：

| Scope | 路径或来源 | 说明 |
| --- | --- | --- |
| Global | `~/.codeium/windsurf/memories/global_rules.md` | 单文件，所有 workspaces 生效，always on，官方限制 6000 字符 |
| Workspace | `.windsurf/rules/*.md` | 每条 rule 一个文件，每个文件有 activation mode，官方限制 12000 字符 |
| AGENTS.md | workspace 任意目录 | 进入同一套 Rules engine，root always-on，子目录 auto-glob |
| System | macOS `/Library/Application Support/Windsurf/rules/*.md`、Linux `/etc/windsurf/rules/*.md`、Windows `C:\ProgramData\Windsurf\rules\*.md` | Enterprise 场景由 IT 部署，对用户只读 |

Workspace rule 的 `trigger` frontmatter 决定激活方式：

| Mode | `trigger` 值 | 适合场景 |
| --- | --- | --- |
| Always On | `always_on` | 极短、所有任务都需要的硬规则 |
| Model Decision | `model_decision` | 让模型按 description 判断是否读取全文 |
| Glob | `glob` | 测试、前端、后端、文档等按路径触发 |
| Manual | `manual` | 需要时 `@rule-name` 手动引用 |

规则要短、具体、可执行。官方也提醒不要写“write good code”这类泛泛规则，因为模型训练里已经有类似常识。

## 8. AGENTS.md：零 frontmatter 的目录规则

官方 AGENTS.md 页面说明，创建 `AGENTS.md` 或 `agents.md` 后，Windsurf 会自动发现，并送入和 `.windsurf/rules/` 相同的 Rules engine。区别是：`AGENTS.md` 不需要 frontmatter，activation mode 由文件位置推断。

自动作用域：

- workspace root 的 `AGENTS.md`：always-on，所有消息都会包含。
- 子目录 `AGENTS.md`：自动生成类似 `<directory>/**` 的 glob，仅在 Cascade 读取或编辑该目录文件时生效。
- 文件名大小写不敏感。
- git 仓库中，Windsurf 会搜索 workspace 和子目录，也会向上搜索父目录直到 git root。

推荐结构：

```text
my-project/
  AGENTS.md              # 全项目约定
  frontend/AGENTS.md     # 前端目录约定
  backend/AGENTS.md      # 后端目录约定
  docs/AGENTS.md         # 文档目录约定
```

根层写全项目硬规则，子目录只写更具体的补充，不重复父级规则。

## 9. .codeiumignore：先排除不该进入上下文的内容

官方 Windsurf Ignore 页面说明，默认会忽略：

- `.gitignore` 指定路径。
- `node_modules`。
- 以 `.` 开头的隐藏路径。

如果需要进一步控制，在仓库根目录添加 `.codeiumignore`，语法类似 `.gitignore`。企业客户也可以在 `~/.codeium/.codeiumignore` 放全局规则。官方还说明，被忽略文件不会被索引，也不会计入 Indexing Max Workspace Size file counts；位于 `.gitignore` 的文件不能被 Cascade 编辑。

建议优先排除：

```text
.env*
**/*.pem
**/*.key
secrets/
credentials/
node_modules/
.next/
dist/
coverage/
logs/
*.sqlite
*.dump
exports/
```

> [!WARNING]
> **不要把密钥写进 Rules 或 AGENTS.md**。这些文件是给模型看的上下文，不是凭据存储。MCP、部署和 API 认证应走环境变量、系统密钥管理或 Windsurf 支持的配置机制。

## 10. 推荐落点

真实团队可以按这套边界落地：

| 内容 | 推荐位置 |
| --- | --- |
| 个人偏好，例如“默认用中文解释” | global rule |
| 仓库整体架构、命令入口、禁止事项 | root `AGENTS.md` |
| 前端、后端、文档目录专属约定 | 子目录 `AGENTS.md` |
| 针对测试文件、迁移文件、MDX 文件的格式要求 | `.windsurf/rules/*.md` + `glob` |
| 发布流程、PR 审查流程 | Workflow |
| 需要脚本、模板、参考文件的复杂任务 | Skill |
| 一次性背景事实 | Memory |
| 不应进入上下文的路径 | `.codeiumignore` |
| 跨仓库团队知识 | Remote Indexing / Knowledge Base |

这个边界能减少“模型有时记得、有时忘了”的问题，也能让并行 agent、团队成员和代码评审看到同一套项目约束。

## 本章自检

完成本章后，用这 7 个问题检查：

1. Context Awareness 和 Rules 分别解决什么问题？
2. Fast Context 提升了什么，不能替代什么？
3. Remote Indexing 和 Knowledge Base 的团队可见性风险是什么？
4. 为什么团队规范不应该只放在 Memories？
5. root `AGENTS.md` 和子目录 `AGENTS.md` 分别什么时候生效？
6. 哪些路径应该进 `.codeiumignore`？
7. 什么时候该写 Workflow，什么时候该写 Skill？

通过标准：你能为一个真实仓库画出 `AGENTS.md`、`.windsurf/rules/`、`.codeiumignore`、pinned context、remote indexing 和 workflow/skill 的落点图。

## 官方来源

- [Context Awareness Overview](https://docs.windsurf.com/context-awareness/overview) —— 官方 RAG、默认上下文、pinned context、Knowledge Base 说明。
- [Fast Context](https://docs.windsurf.com/context-awareness/fast-context) —— 官方 SWE-grep / SWE-grep-mini 检索 subagent 说明。
- [Remote Indexing](https://docs.windsurf.com/context-awareness/remote-indexing) —— 官方远程仓库索引、安全保证和适用计划说明。
- [Windsurf Ignore](https://docs.windsurf.com/context-awareness/windsurf-ignore) —— 官方 `.codeiumignore`、默认忽略规则、global ignore 和索引限制说明。
- [Memories & Rules](https://docs.windsurf.com/windsurf/cascade/memories) —— 官方 Memories、Rules、AGENTS.md、Workflows、Skills 的区别，以及 Rules storage、limits 和 activation modes。
- [AGENTS.md](https://docs.windsurf.com/windsurf/cascade/agents-md) —— 官方 `AGENTS.md` / `agents.md` 自动发现、root always-on、子目录 auto-glob 和最佳实践。

## 接下来去哪

<Cards>
  <Card title="终端与命令控制" description="继续学习 auto-execution、allow/deny list、专用终端和命令审批边界。" href="/docs/windsurf/official/03-terminal-command-control" />
  <Card title="MCP 集成" description="继续学习 Marketplace、mcp_config.json、stdio/HTTP/SSE、认证和 registry。" href="/docs/windsurf/official/04-mcp-integration" />
</Cards>
