---
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="/zh-Hant/docs/windsurf/official/03-terminal-command-control" />
  <Card title="MCP 整合" description="繼續學習 Marketplace、mcp_config.json、stdio/HTTP/SSE、認證和 registry。" href="/zh-Hant/docs/windsurf/official/04-mcp-integration" />
</Cards>
