上下文、Rules 与 AGENTS.md 怎么放
给出 Windsurf 项目规则落地模型，说明 Context Awareness、Memories、Rules、AGENTS.md、.windsurf/rules 和 .codeiumignore 的分工。
Windsurf 用久之后，效率差距来自上下文治理。会用的人会把“该看的内容”和“该遵守的规则”分开维护；不会用的人每次都在 prompt 里重复同样的话，然后抱怨 Cascade 忘记。
本篇目标：给真实仓库设计一套 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 个人权限逐个判断。
团队做法：
- 先列出允许索引的仓库和文档。
- 明确 owner。
- 明确是否允许 Store Snippets。
- 明确离职、项目结束、客户撤权时怎么移除。
4. Rules 与 AGENTS.md 负责“按规矩做”
官方 Memories & Rules 页面建议：如果希望 Cascade 稳定复用某条知识，优先写成 Rule 或加入 AGENTS.md，不要只依赖 Memories。
推荐结构：
my-project/
AGENTS.md
.codeiumignore
.windsurf/
rules/
tests.md
docs-mdx.md
frontend/
AGENTS.md
backend/
AGENTS.mdroot 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。
建议起点：
.env*
**/*.pem
**/*.key
secrets/
credentials/
private/
exports/
*.sqlite
*.dump
node_modules/
.next/
dist/
build/
coverage/
logs/如果一个路径既不该被索引，也不该被 Cascade 读取或编辑，就放进去。密钥不要写进 rules，不要写进 AGENTS.md，也不要写进 workflow 或 skill。
7. 每月轻量维护
每月检查一次：
- root
AGENTS.md是否还有过期命令。 - 子目录规则是否重复父级内容。
.windsurf/rules是否还有对应文件类型。.codeiumignore是否覆盖新增敏感目录。- Memories 里是否有应该转成长期规则的内容。
- 规则是否和真实代码风格冲突。
判断一条规则是否值得保留，可以问三件事：它会不会影响模型的具体操作；未来一个月是否仍有效；是否能被当前目录或 glob 精准命中。三个问题只要有两个是否定，就不要写进长期规则。
官方来源
- Context Awareness Overview —— 官方 RAG、默认上下文、pinned context、Knowledge Base 说明。
- Fast Context —— 官方 SWE-grep / SWE-grep-mini 检索说明。
- Remote Indexing —— 官方远程仓库索引说明。
- Memories & Rules —— 官方 Memories、Rules、AGENTS.md、Workflows、Skills 对比。
- AGENTS.md —— 官方目录规则发现和作用域说明。
- Windsurf Ignore —— 官方
.codeiumignore说明。
本篇自检
- 哪些内容属于检索上下文，哪些属于行为规则？
- 团队规范为什么不该只放 Memory？
- root
AGENTS.md和子目录AGENTS.md分别写什么？ .windsurf/rules什么时候比AGENTS.md更合适？- 哪些路径必须进入
.codeiumignore？