上下文、规则与 AGENTS.md

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

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

1. 先分清两类上下文

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

这两类不能混用。比如“这个目录是前端组件，只能改 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 侧的个人访问控制。

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

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

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

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，存储在本机：

~/.codeium/windsurf/memories/

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

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

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

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

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

规则要短、具体、可执行。官方也提醒不要写“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。

推荐结构：

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 编辑。

建议优先排除：

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

10. 推荐落点

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

这个边界能减少“模型有时记得、有时忘了”的问题，也能让并行 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 —— 官方 RAG、默认上下文、pinned context、Knowledge Base 说明。
• Fast Context —— 官方 SWE-grep / SWE-grep-mini 检索 subagent 说明。
• Remote Indexing —— 官方远程仓库索引、安全保证和适用计划说明。
• Windsurf Ignore —— 官方 .codeiumignore、默认忽略规则、global ignore 和索引限制说明。
• Memories & Rules —— 官方 Memories、Rules、AGENTS.md、Workflows、Skills 的区别，以及 Rules storage、limits 和 activation modes。
• AGENTS.md —— 官方 AGENTS.md / agents.md 自动发现、root always-on、子目录 auto-glob 和最佳实践。

接下来去哪