Skip to main content

當我的多 Repo 規則開始打架 - Cursor AI 治理首部曲

系列導覽

Cursor AI 多 Repo 規則治理實戰系列

  1. 本篇：當我的多 Repo 規則開始打架 - Cursor AI 治理首部曲 — 痛點診斷與隔離原則
  2. Cursor AI 規則集中管理行得通嗎？ - 我的翻車之路 - 反模式與官方對照
  3. 多 Repo 的 Cursor AI 規則治理 - 我怎麼活下來的 - 落地案例與執行藍圖
本文摘要
  • 目標讀者：架構師、多 Repo 環境的技術主管、導入 Cursor AI 的團隊 Lead。
  • 讀完你能：用自評表判斷團隊規則亂象的嚴重度，並理解 Team／Project／User 三層隔離是後續一切治理手段的前提。
  • 延伸閱讀：對 Agentic AI 治理框架有興趣的讀者，可參考Agentic AI 加入後，我看到的隱憂與治理破口（非必要）。

前言：Repo 一多，打架就開始了​

在上一篇文章裡，我提到了多 Repo 環境中容易發生的規則漂移問題。

如果你的團隊跟我的一樣，同時得要維護多個不同的 Repo，那你可能也已經經歷過像這樣的尷尬局面了：

  • Repo A 的 .cursor/rules/architecture.mdc 明確定義要用 Repository Pattern 存取資料
  • Agentic AI 在處理 Repo B 的時候因為上下文不足，直接戳 Database、完全不走 Repository Pattern
  • Repo C 裡甚至根本沒有設定 .cursor/rules/，所以每次都得要手動叮嚀 Agentic AI

然後當某個功能的改動同時要跨越 A、B、C 三個 Repo 時，Agentic AI 的實作風格也就五花八門，Code Review 成了一場「我們怎麼定義這件事」或是「都是 AI 惹的禍」的無盡辯論大會。

規則衝突混亂的困境

讓我先試著用這篇文章來協助你診斷問題到底有多嚴重，文章後面的判斷標準也可以作為參考。至於「規則到底該放哪裡」「該怎麼落地」，就容我留到後面兩篇再說囉。

我的多 Repo 架構與日常挑戰​

在繼續下去之前，先花點時間讓大家對我的部門中所謂的「多 Repo」有個基礎的了解。

我們的系統是基於 Component-Based 和 Clean Architecture 的原則建立的，這意味著一個簡單的業務異動，往往會牽動一整片 Repo 叢林：

謎之音

到底是誰決定這樣切的!? 好像是我...

術語澄清

本文中的 Repository Repo 是指一個具體的程式碼倉庫名稱，用來存放資料存取層的程式碼。 這與設計模式中的 Repository Pattern（資料庫存取設計模式）是不同的概念。後者是一種程式設計方法，前者是我們的組織結構。

物理 Repo對應的 Clean Architecture 階層功能
Application RepoFrameworks & Drivers (Entry Points)定義如何啟動應用、設定 DI 容器、配置 Middleware 與 Routing
Domain Library ReposEntities + Use Cases最純粹的邏輯層，所有商業邏輯都集中在這邊
Repository RepoInterface Adapters + Drivers將 Use Case 定義的介面轉化為具體的 SQL/NoSQL 操作

除了上述的 Repos 之外，我們還有一個很重要的 KB Repo，它是一個基於 Docusaurus 打造的部門知識庫，存放了包含但不限於下列各類型的文件：

  • 架構決策記錄（ADR, Architecture Decision Record）：為什麼要採用某個技術方案、背景與權衡
  • Domain Knowhow 文件：特定領域的專業知識和約束
  • 設計規格書：各專案的需求分析、設計決策、限制條件
  • 過去的經驗教訓：曾經踩過的坑、解決方案

在我的部門裡，需求的落地流程通常是這樣的：

  1. 分析與設計：由 Project Lead 進行功能的分析與設計，並將決策記載於 KB Repo。

  2. 任務領取：工程師領取子功能任務，依照 KB 的設計開始實作。

  3. 實作：由於一個功能異動往往橫跨 Application、Domain 與 Repository，工程師們很自然的演化出兩種不同的開發風格：

    • 「逐一擊破模式 (The Purist)」：一次只開一個 Repo 修改，模擬 Library 被使用的真實情境。AI 每次只載入當前 Repo 的 .cursor/rules/，環境純淨但缺乏跨層級上下文。
    • 「大混戰模式 (The Brawler)」：為了方便，一次載入所有 Repo（使用 Local Reference）。這讓 AI 更有機會看見全貌，但也開啟了規則衝突的大門。

大混戰模式下的三大衝突機制​

當你把多個 Repo 同時載入 Cursor AI 的 multi-root workspace 時，規則打架就有了舞台。

下面這張圖大概畫出了規則從哪裡來、又是怎麼會撞在一起的：

我自己觀察到在大混戰模式下比較容易踩到的衝突大概有這幾種：

衝突機制觸發情境具體現象主要後果
alwaysApply: true 的重複載入多個 Repo 的規則同時設 alwaysApply: trueCursor AI 不會自動去除重複的規則，衝突規則同時進入 System Prompt（如「英文註解」vs「繁體中文註解」）Token 增加、輸出不穩定、風格矛盾
過度寬鬆的 glob 導致規則越界寬鬆 glob（如 ["**/*.cs"]）搭配跨 Repo 操作規則意外匹配其他 Repo 的同類型檔案規則失去隔離性，不同層級程式碼被錯誤約束
不同操作模式的上下文融合差異Chat（Ctrl+L）或 Composer 進行跨 Repo 任務Inline Edit 隔離性高；Chat/Composer 積極融合多 Repo 規則AI 試圖同時滿足衝突規範，產生風格混亂

三種衝突的根源都一樣：規則的作用範圍不夠精確。

alwaysApply: true 是地圖砲、寬 glob 是散彈槍、Chat 模式則是把所有彈藥一次打出去。

相對應的解法如下：

  • alwaysApply: true： 避免跨 Repo 設定衝突的 alwaysApply 規則；改用精準 globs

  • 過度寬鬆的 glob： 使用精準相對路徑 glob（如 [src/infrastructure/**/*.cs]）

  • 不同操作模式的上下文融合差異： Prompt 中明確指定範圍（如「僅限 Application 層」）

重要區別

上面的三大衝突機制是 Cursor AI 在技術層面 的問題——「為什麼會打架」。 下面的四大痛點是 規則治理在管理層面 的問題——「打完架了該怎麼辦」。

換句話說：衝突機制是症狀，痛點是病因。

跨多 Repo 規則治理的四大痛點​

現在我們來看管理層面的問題。這四個痛點，是我觀察到在多 Repo 環境下，治理本身容易崩壞的核心原因：

核心痛點症狀範例核心代價從我的角度看
規則內容或版本不同步同一條規則在不同 Repo 內容不一，AI 為了符合規則會自己建 Adapter整合測試失敗次數顯著增加；需要更多人工驗證讓 AI 寫 Adapter 來修補 API 差異，就像是在傷口上貼美工膠帶
規則優先級混亂Project Rules 的「測試檔案可寫死帳密」永遠被 Team Rules 的「禁止寫死帳密」擋下來團隊因規則衝突而停滯，開發速度下降Team Rules 是聖旨，但 AI 有時候會覺得那只是「參考文獻」
人工同步成本每次更新規則，都要在 N 個 Repo 間手動複製貼上，更常發生的是貼 A 漏 B維護成本隨 Repo 數量增長；容易發生遺漏工程師的靈魂不該消耗在無止盡的 Ctrl+C 和 Ctrl+V 無窮迴圈中
可追蹤性破裂缺乏 Git Blame，不知道規則為何被改、何時被改規則審計困難；事後責任歸屬不清查證規則來源像是一場考古活動，或者是對著螢幕通靈

📝 重要提醒：上述症狀來自我參與過的多個專案的實務觀察。具體的定量影響因團隊規模、Repo 數量、規則複雜度而異，建議根據你的環境進行實際量測。

這四大痛點都有一個共通點：規則沒有被當成工程資產來管理。

一旦沒有版控、沒有明確擁有者、沒有同步機制，規則治理就是空中樓閣。

你的團隊也有一樣的痛嗎？請服用快速自評表​

如果你的團隊也有遇到類似的規則治理問題，又想要簡單的量化問題的程度；不妨在 Retro 會議的時候讓團隊成員也透過下面這份自評表來進行評分：

評估面向🟢 輕度（0 分）🟡 中度（1 分）🔴 重度（2 分）
Repo 數量1–2 個3–5 個6 個以上
規則同步方式有自動化或統一範本有範本但靠人工複製各 Repo 各自為政
multi-root 使用頻率很少用偶爾用天天用（大混戰模式）
alwaysApply: true 密度幾乎沒用部分規則使用大多數規則都開
規則版控全部進 Git部分進 Git沒有版控或散落各處
規則擁有者有明確負責人模糊、靠默契沒有人負責

計分方式：把每一列的分數加總。

總分嚴重度下一步建議
0–3 分輕度 — 還算健康先建好隔離原則，預防未來惡化
4–7 分中度 — 開始有痛感了建議看完本系列三篇，挑最痛的 1–2 個點先改
8–12 分重度 — 該認真治了強烈建議照 Part 3 的 Phase 計畫逐步推進

可以讓每個人獨立打分數，之後再大家一起對答案，然後訂出要改善的方向和目標。

現在就可以做的事

如果你的團隊自評分數在 4-7 分（中度問題），可以先：

  1. 建立規則清單：在 Confluence/Wiki 或 README 中列出「我們現在有哪些規則」，即使它們現在還很散亂
  2. 選一個 Repo 試點：不必一次改所有 Repo，先在最痛的一個 Repo 開始建立 .cursor/rules/ 目錄
  3. 邀請團隊認可：在 Retro 或技術會議中分享自評結果，讓大家達成共識「我們有問題」是第一步

如果你的團隊已經 8+ 分（重度問題），建議耐心讀完三篇系列文，然後按 Part 3 的 Phase 計畫逐步推進——急不得。

Cursor AI 的 SSOT 隔離原則：Team／Project／User 各管什麼​

SSOT（Single Source of Truth，單一真實來源）是指在系統中應該只有一個權威的資料來源。在規則治理中，Team/Project/User 三層就是按這個原則隔離的。

知道問題有多嚴重之後，下一步是搞清楚 Cursor AI 本身提供的規則分層機制，畢竟要用對的方法，才能把事情做對。

Cursor AI 支援 4 種規則：Team Rules、Project Rules、User Rules、Agent。

不過這篇我們先專注在前三種比較直覺的規則， Agent 就留到之後的文章再來好好討論它。

這邊就把前三種規則整理成一個比較表，方便大家快速對照：

規則類型定位範例儲存位置與版控優先級
Team Rules企業級護欄：確保合規，防止事故禁止寫死帳密Cursor AI Dashboard（✗ 無版控）1（最高）
Project Rules專案級慣例：確保實作風格一致強制使用 Repository Pattern.cursor/rules/（✓ Git）2（中）
User Rules個人化偏好：優化開發體驗一律以繁體中文回覆Cursor AI Settings（✗ 無版控）3（最低）
小提示

三個不同層級的規則就像是國家的法律（Team Rules）、公司的規章（Project Rules）與個人的生活習慣（User Rules）之間的關係。你可以習慣不吃早餐，但你不能在辦公室抽菸，更不能違反憲法。

下面這個簡化版的表格，我個人覺得還蠻適合用來跟團隊成員分享的，不妨在新增規則之前先瞄一眼。

層級定位誰維護能被覆蓋嗎？
Team Rules不能違反的底線IT / 架構師不能
Project Rules這個 Repo 的遊戲規則團隊 / Tech Lead不能覆蓋 Team，但可補充
User Rules我個人的偏好自己被 Team 和 Project 覆蓋

規則載入順序：Cursor AI 怎麼決定聽誰的？​

搞清楚三層各管什麼之後，你可能會好奇：當 Cursor AI 收到一個 Prompt 的時候，它到底怎麼把這些規則組合在一起？

簡單來說：所有適用的規則都會被合併成一個統一的 Prompt。

依據 Cursor 官方文件 裡的描述：當規則發生衝突時，優先級較高的規則會被採用。

小提示

隔離原則的核心就一句話：規則應該按照「作用域」和「優先級」明確分工，確保不同層級的規則各司其職、互不干擾。

小結：打架打完了，接下來呢？​

讀到這邊，你應該對幾件事情有感覺了：

Recap
  1. 多 Repo + Agentic AI 的組合，會把規則不一致的問題放大好幾倍。
  2. Cursor AI 的三層規則（Team / Project / User）設計上就有隔離機制，但如果不刻意治理，它們就會在 multi-root workspace 裡打得不可開交。
  3. 四大痛點（不同步、優先級混亂、人工同步、可追蹤性破裂）的根源是：規則沒有被當成工程資產來管理。

如果你已經服用了前面的自評表，也知道自己團隊的嚴重度了。接下來的問題就是：規則到底該放在哪裡？

我在這條路上翻過不少車——試過把規則全部收斂到 KB、也試過開一個獨立的規則 Repo 來當「規則控制中心」，結果都是悲劇收場。

下一篇我會從我踩過的坑談起：為什麼把 KB 或獨立規則 Repo 當成「集中式規則控制中心」往往行不通，再對照 Cursor AI 官方指南看看官方是怎麼想的。

如果你還沒填完自評表，不妨花個幾分鐘做個小健檢，再決定下一步。

如果你也剛開始走在規則治理這條路上，下一篇 Part 2 應該會讓你更清楚哪些坑可以直接跳過。

參考資源​