---
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="/zh-Hant/docs/windsurf/understanding/03-cascade-mental-model" description="規則只有配上正確的任務迴圈才生效" />
  <Card title="MCP / Skills / Workflows" href="/zh-Hant/docs/windsurf/understanding/05-mcp-skills-workflows" description="規則之外，能力包與流程怎麼分工" />
  <Card title="模型與用量策略" href="/zh-Hant/docs/windsurf/understanding/07-model-usage-strategy" description="規則跟模型策略一起決定最終質量" />
  <Card title="官方上下文 / 規則" href="/zh-Hant/docs/windsurf/official/02-context-rules-agents" description="對照官方 Rules / AGENTS.md / Memories 文件" />
  <Card title="Understanding 總覽" href="/zh-Hant/docs/windsurf/understanding" description="回到學習路徑地圖" />
</Cards>
