Windsurf - 持久化上下文減少重複索引策略

jacklam98
5 阅读5分钟

Windsurf - 持久化上下文減少重複索引策略

背景

  • 大型程式碼庫在每次啟動對話時重新掃描，會讓 Cascade 消耗大量 token，亦拉長規劃與生成時間。
  • 官方文件將持久化上下文拆為兩個面向：Memories 由系統自動記錄對話重點，Rules 由使用者手動撰寫，兩者會在後續對話中優先載入，避免重複提醒【docs.windsurf.com/windsurf/cascade/memories】。
  • 實務案例顯示，若再搭配 AGENTS.md、工作流（Workflows）與 MCP 工具鏈，可把專案約束、資料來源與重點摘要分散維護，Cascade 便能在不用重新讀完整 repo 的情況下取得核心脈絡【docs.windsurf.com/windsurf/cascade/agents-md】【www.paulmduvall.com/using-winds…

流程總覽

  • 建立 .windsurf/rules/ 專案規則，持久保存跨對話約束。
  • 依資料夾放置 AGENTS.md，把區域性約定交由 Cascade 自動套用。
  • 餵給 Cascade 可重複引用的 Memories，特別是系統概覽、Story Mapping 與決策記錄。
  • 透過 Windsurf Workflows 定期產出或更新「可讀版摘要」與入口清單，縮短模型讀取時間。
  • 需要更進階的索引時，啟用 MCP Context Manager 或自建 MCP server，把外部文件與索引交給協力工具處理。

步驟詳解

1. 建立跨對話基準 .windsurf/rules

  • 規則檔可切成多個主題，並在 YAML frontmatter 中設定觸發模式（always_on、model_decision、glob），讓 Cascade 只讀必要內容，避免 12,000 字元上限過早耗盡【design.dev/guides/windsurf-rules】。
  • 建議至少準備一份 project-overview.md（描述技術棧、資料流、部署流程）與 coding-standards.md（格式、測試、錯誤處理）。
  • 範例：
---
trigger: model_decision
description: "核心架構與模組邊界，適用於任何需要理解系統整體設計的任務"
---
# 系統概覽
- 後端使用 NestJS + PostgreSQL，採 CQRS + Event Sourcing。
- 前端為 Next.js App Router，資料透過 GraphQL Gateway 取得。
- 共用型別維護於 packages/types/，任何跨專案型別請同步更新。

2. 使用 AGENTS.md 實作目錄分層規則

  • AGENTS.md 只要放在資料夾下即可生效；父層的說明會自動被子層繼承，讓你把細節拆散維護而不必集中在單一規則檔【docs.windsurf.com/windsurf/cascade/agents-md】。
  • 建議內容聚焦在「該資料夾專屬」的命名、目錄結構、範本程式碼，避免與全域規則重複。
# domain/orders 指南
- 只允許使用 Domain Event 觸發狀態改變，禁止直接呼叫 Repository `save`。
- Aggregate root 檔名採 `*.aggregate.ts`，對應的測試放在 `__tests__/`。
- 若需要跨 bounded context 合作，先更新 docs/messaging.md，再產生新的 integration event。

3. 維護專案記憶（Memories）

  • 任何需要長期記住的約束（例：用戶故事、里程碑、踩坑）都可以在 Cascade 對話中輸入「create a memory of ...」，或在設定介面手動新增，之後每次會話系統會自動給予摘要，不計算額外成本【docs.windsurf.com/windsurf/cascade/memories】。
  • 實務經驗指出，將「需求追蹤表」「決策記錄」「常見錯誤排除」寫成記憶，搭配規則與 workflow，可讓新人在數小時內完成上手並維持一致品質【www.paulmduvall.com/using-winds…

4. 用 Workflows 產出可重複引用的摘要

  • Workflows（.windsurf/workflows/*.md）可透過 / 命令觸發一系列步驟，例如「掃描最新 commit → 生成更新摘要 → 將結果寫回 docs/overview.md」，把繁雜的整理流程交給 Cascade 自動化【docs.windsurf.com/zh/windsurf/cascade/workflows】。

  • 建議建立至少兩條流程：

    1. /codebase-digest：抓取 git diff HEAD~1、請 Cascade 生成 300 字以內的更新備忘並追加到 docs/changelog.md。
    2. /module-tour：依資料夾清單遍歷、輸出重點模組與入口點，再存成 docs/architecture/INDEX.md。

  • 如需持續調整流程，可參考部落格中的範例 repository，把 workflow 與規則綁定使用，並在流程最後提示對應記憶或規則的位置【www.paulmduvall.com/using-winds…

5. 擴充 MCP 與外部索引

  • 當單靠規則與記憶仍無法涵蓋整個知識體（如多 repo、legacy 系統），可在 settings.json 加上 MCP server 設定，或安裝社群的「Windsurf Cascade Context Manager」Skill，讓外部服務先完成模組索引與優先級排序，再把重點上下文回灌給 Cascade【mcpmarket.com/tools/skills/windsurf-cascade-context-manager-1】。
  • 常見做法：以 Filesystem MCP 暴露 docs/、ADR/ 或生成的超過 4k 字元摘要檔給 Cascade 查閱；或使用 Database MCP 直接查表，避免模型猜測 schema。

執行檢查清單

  • .windsurf/rules/ 是否依主題拆分並控制在 12k 字限制內？
  • 主要子系統資料夾是否放置 AGENTS.md？
  • 最新的系統概覽、決策記錄是否已轉為 Memories 或固定在 workflow 輸出？
  • 是否有日常 workflow（如 /codebase-digest）協助產出可供閱讀的摘要？
  • 是否評估需要 MCP/Skill 來同步外部知識庫或大型索引？

常見問題與排除

  • 為什麼 Cascade 還是載入過多檔案？

    • 檢查是否存在過多 always_on 規則；可改為 model_decision 或 glob 限定並縮短內容【design.dev/guides/windsurf-rules】。
    • 確認 workflow 產出的摘要字數適中，避免又把整個 diff 貼回去。

  • AGENTS.md 跟規則重複會怎樣？

    • Cascade 會合併上下文，重複內容不會報錯，但會浪費字元。建議在 AGENTS.md 保留「該資料夾專屬」提示，把通用規範留在規則或 memories【docs.windsurf.com/windsurf/cascade/agents-md】。

  • Memories 超過需要的內容怎麼管理？

    • 從 Settings → Customizations → Memories 中手動移除舊資訊，並考慮把常態性說明移至規則或 workflow 生成的文件，以降低噪音【docs.windsurf.com/windsurf/cascade/memories】。

參考資料

avatar
文章
阅读
粉丝