上下文、規則與 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 和最佳實踐。

接下來去哪