---
title: "上下文、Rules 与 AGENTS.md 怎么放"
description: "给出 Windsurf 项目规则落地模型，说明 Context Awareness、Memories、Rules、AGENTS.md、.windsurf/rules 和 .codeiumignore 的分工。"
verifiedAt: "2026-05-09"
---

Windsurf 用久之后，效率差距来自上下文治理。会用的人会把“该看的内容”和“该遵守的规则”分开维护；不会用的人每次都在 prompt 里重复同样的话，然后抱怨 Cascade 忘记。

> [!TIP]
> **本篇目标**：给真实仓库设计一套 Windsurf 上下文落点，让 Cascade 知道该看什么、该按什么规则做、什么永远不该读。

## 1. 先分成两条线

一条是“检索上下文”：Cascade 需要哪些代码、文件、文档和仓库信息。另一条是“行为规则”：Cascade 应该怎么行动、哪些边界不能越过。

| 问题 | 机制 |
| --- | --- |
| 当前任务需要引用哪些文件 | Context Awareness、Pinned context、Fast Context |
| 团队要共享哪些仓库知识 | Remote Indexing、Knowledge Base |
| 项目长期硬规则 | root `AGENTS.md`、global / workspace rules |
| 目录局部约定 | 子目录 `AGENTS.md` |
| 文件类型约定 | `.windsurf/rules/*.md` + glob |
| 一次性背景 | Memory 或本轮 prompt |
| 不该被读取 | `.codeiumignore` |

不要把这些混在一个大提示词里。混在一起会导致规则过长、上下文污染、敏感路径暴露和团队不可复现。

## 2. Context Awareness 负责“找得到”

官方 Context Awareness 页面说明，Windsurf 默认会考虑当前文件、打开文件、本地代码库索引、Pro 的更高上下文/索引限制，以及 Teams/Enterprise 的远程仓库索引。

实战原则：

- 任务依赖具体接口时，pin 接口定义，不要 pin 整个仓库。
- 写单测时，pin 被测类和相关 fixture。
- 读内部框架时，pin 最小示例目录。
- 大任务先让 Cascade 说“还需要读哪些文件”，不要一次性把所有文件塞进去。
- 任务结束后清理不再相关的 pinned context。

Fast Context 是检索加速器，不是权限放大器。官方说明它用 SWE-grep / SWE-grep-mini 作为 specialized subagent 检索代码。它能更快找到相关片段，但不会替代 `.codeiumignore`、Rules 和人工边界。

## 3. Remote Indexing 和 Knowledge Base 只给团队用

Remote Indexing 适合 Teams/Enterprise 跨仓库场景。官方说明支持从 GitHub、GitLab、BitBucket 添加 repo，由 Windsurf 服务器在 **isolated tenant**（独立租户——Windsurf 给每个团队分配一块专属处理空间，团队之间数据互相隔离）中创建 index。它适合团队让 Cascade 查询共享仓库，不适合未经授权索引客户仓库。

Knowledge Base 目前是 Beta，只面向 Teams/Enterprise，官方说明支持连接 Google Docs，最多添加 50 个文档。关键风险是：admin 加进去后，团队用户都能访问，不再按 Google Drive 个人权限逐个判断。

团队做法：

1. 先列出允许索引的仓库和文档。
2. 明确 owner。
3. 明确是否允许 Store Snippets。
4. 明确离职、项目结束、客户撤权时怎么移除。

## 4. Rules 与 AGENTS.md 负责“按规矩做”

官方 Memories & Rules 页面建议：如果希望 Cascade 稳定复用某条知识，优先写成 Rule 或加入 `AGENTS.md`，不要只依赖 Memories。

推荐结构：

```text
my-project/
  AGENTS.md
  .codeiumignore
  .windsurf/
    rules/
      tests.md
      docs-mdx.md
  frontend/
    AGENTS.md
  backend/
    AGENTS.md
```

root `AGENTS.md` 写项目底线：

- 技术栈和运行命令。
- 禁止触碰的目录。
- 敏感信息边界。
- 命令执行规则。
- 多文件改动必须先计划。
- 验证和提交要求。

子目录 `AGENTS.md` 写局部差异：

- 前端目录：组件分层、设计系统、状态管理、a11y。
- 后端目录：handler/service/database 边界。
- 内容目录：frontmatter、内部链接、图片、SEO 字段。
- infra 目录：只读优先、禁止自动 apply/destroy。

`.windsurf/rules/*.md` 写按 glob 触发的规则，例如测试文件、迁移文件、MDX 页面、UI 组件。它的价值是避免所有任务都背同一套长规则。

## 5. Memory 只放短期背景

Memories 是本机 workspace 状态。官方说明它们存储在 `~/.codeium/windsurf/memories/`，不会提交到仓库，也不会跨 workspace 共享。

适合 Memory：

- 本轮重构的临时阶段目标。
- 当前任务的短期背景。
- 个人偏好。

不适合 Memory：

- 团队编码规范。
- 架构边界。
- 测试命令。
- 发布流程。
- 密钥路径或客户信息。

如果一条 Memory 反复出现，说明它该进入 `AGENTS.md` 或 `.windsurf/rules/`。

## 6. .codeiumignore 是底线

`.codeiumignore` 解决的不是“模型怎么写”，而是“模型不该看什么”。官方说明默认会忽略 `.gitignore` 指定路径、`node_modules` 和隐藏路径；你可以在 repo root 添加 `.codeiumignore`，企业也可以用 `~/.codeium/.codeiumignore`。

建议起点：

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

如果一个路径既不该被索引，也不该被 Cascade 读取或编辑，就放进去。密钥不要写进 rules，不要写进 `AGENTS.md`，也不要写进 workflow 或 skill。

## 7. 每月轻量维护

每月检查一次：

1. root `AGENTS.md` 是否还有过期命令。
2. 子目录规则是否重复父级内容。
3. `.windsurf/rules` 是否还有对应文件类型。
4. `.codeiumignore` 是否覆盖新增敏感目录。
5. Memories 里是否有应该转成长期规则的内容。
6. 规则是否和真实代码风格冲突。

判断一条规则是否值得保留，可以问三件事：它会不会影响模型的具体操作；未来一个月是否仍有效；是否能被当前目录或 glob 精准命中。三个问题只要有两个是否定，就不要写进长期规则。

## 官方来源

- [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 检索说明。
- [Remote Indexing](https://docs.windsurf.com/context-awareness/remote-indexing) —— 官方远程仓库索引说明。
- [Memories & Rules](https://docs.windsurf.com/windsurf/cascade/memories) —— 官方 Memories、Rules、AGENTS.md、Workflows、Skills 对比。
- [AGENTS.md](https://docs.windsurf.com/windsurf/cascade/agents-md) —— 官方目录规则发现和作用域说明。
- [Windsurf Ignore](https://docs.windsurf.com/context-awareness/windsurf-ignore) —— 官方 `.codeiumignore` 说明。

## 本篇自检

1. 哪些内容属于检索上下文，哪些属于行为规则？
2. 团队规范为什么不该只放 Memory？
3. root `AGENTS.md` 和子目录 `AGENTS.md` 分别写什么？
4. `.windsurf/rules` 什么时候比 `AGENTS.md` 更合适？
5. 哪些路径必须进入 `.codeiumignore`？

## 接下来去哪

<Cards>
  <Card title="Cascade 心智模型" href="/docs/windsurf/understanding/03-cascade-mental-model" description="规则只有配上正确的任务循环才生效" />
  <Card title="MCP / Skills / Workflows" href="/docs/windsurf/understanding/05-mcp-skills-workflows" description="规则之外，能力包与流程怎么分工" />
  <Card title="模型与用量策略" href="/docs/windsurf/understanding/07-model-usage-strategy" description="规则跟模型策略一起决定最终质量" />
  <Card title="官方上下文 / 规则" href="/docs/windsurf/official/02-context-rules-agents" description="对照官方 Rules / AGENTS.md / Memories 文档" />
  <Card title="Understanding 总览" href="/docs/windsurf/understanding" description="回到学习路径地图" />
</Cards>
