上下文、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？