研發團隊如何配置 Cursor 規則在多倉庫中統一架構模式與程式碼規範

研發團隊在推廣 Cursor 時，統一架構模式與程式碼規範的核心路徑為：從早期的單一根目錄檔案 .cursorrules 遷移至模組化專案規則（.cursor/rules/*.mdc），利用 YAML 前置元數據將規範劃分為全域核心約束與檔案路徑級（Glob）邊界，並透過 Cursor Team Rules（團隊規則控制台）或中心化 CI/CD 自動化工作流在跨程式碼倉庫間落實同步與版本治理。

若團隊在規模化使用 AI 開發工具時缺乏系統化約束，極易導致「AI 架構漂移」：不同工程師使用的底層模型生成風格歧異、頻繁幻覺引用已棄用的內部套件、跨層直連資料庫繞過領域服務，甚至在單體大倉（Monorepo）中製造不良的循環依賴。建立結構化、納入版本控制的 Cursor 規則體系，能在最大程度節省模型上下文 Token 的同時，為 AI 程式碼生成提供具確定性的工程邊界。

團隊級研發中的 AI 治理痛點

當組織級工程團隊引入 Cursor 時，開發者往往直接依賴通用基礎模型。模型缺乏團隊特有的架構脈絡，通常會引發以下協同問題：

• 架構分層被突破： AI 補全容易違反系統設計原則，例如在前端介面元件中直接編寫資料庫查詢，或在領域服務層中直接解析特定 HTTP 框架的請求物件。
• 棄用與幻覺依賴蔓延： 模型常依據公開歷史資料推斷相依套件，誤引用團隊已廢棄的舊版內部套件（如呼叫舊版 @company/legacy-ui 而非統一標準 @company/design-system-v2），甚至生成未經資安合規審核的第三方套件。
• 程式碼風格嚴重割裂： 同一專案內，不同成員提交的程式碼在函式式與物件導向風格間徘徊，錯誤處理機制、日誌格式與狀態管理方式缺乏一致性。
• 單元測試品質斷層： AI 生成的測試程式碼經常遺漏邊界斷言，混用淘汰的 Mock 框架，或在重構時完全忽略測試覆蓋。

解決這些問題的關鍵，在於技術架構師必須將組織規範轉化為持久化、隨程式碼庫版本同步演進的結構化規則。

Cursor 規則體系演進：從 .cursorrules 到模組化 .mdc

早期版本中，Cursor 主要依賴位於倉庫根目錄的單一 .cursorrules 純文字檔案。這種模式雖然向下相容，但存在顯著痛點：所有規範一次性全量載入至 Prompt，快速佔滿模型的上下文窗口（Context Window），導致指令互相干擾且模型注意力分散。

Cursor 當前的規範配置機制全面轉向基於 .cursor/rules/ 目錄的 專案規則（Project Rules），採用帶有 YAML Frontmatter 標頭的 .mdc（Markdown Cursor）檔案格式。

.mdc 規則檔案結構

每個 .mdc 檔案由頂部的 YAML 設定元數據與下方的 Markdown 具體技術指令組成：

---
description: 領域服務分層邊界與倉儲模式規範
globs: src/domains/**/*.ts, src/services/**/*.ts
alwaysApply: false
---

# 領域層架構規範

- 領域服務嚴禁直接讀取或解析 HTTP 上下文（例如 Request/Response）。
- 所有資料庫持久化異動必須透過倉儲介面（Repository Port）完成。

規則觸發模式與前置元數據

YAML Frontmatter 決定了該條規則在何種時機被注入模型的上下文：

技術架構師實戰規範藍圖

成熟的工程團隊應當將架構規範切分為權責單一的獨立 .mdc 檔案。以下是針對多層企業級專案的三個實戰配置模板。

1. 全域架構基線 (.cursor/rules/00-core-architecture.mdc)

此檔案作為倉庫頂層約束，在全專案範疇內持續生效。

---
description: 全域架構基線、基準技術棧選型與禁用相依套件清單
alwaysApply: true
---

# 全域架構與技術棧約束

## 技術棧基線
- Node.js 執行環境：v20 LTS
- TypeScript：v5.4+，啟用 `strict: true`
- 前端框架：Next.js App Router (v14+)
- 全域狀態管理：Zustand（嚴禁引入 Redux 或 MobX）

## 嚴格禁用的套件與模式
- 禁用：`axios`（統一使用封裝於 `@lib/api-client` 的原生 `fetch`）
- 禁用：`@company/ui-core-v1`（已棄用；必須使用 `@company/design-system-v2`）
- 禁用：`moment.js`（統一使用 `date-fns`）

## 程式碼品質硬性要求
- 嚴禁出現顯式 `any`；動態未知型別使用 `unknown` 並配合型別守衛。
- 採用提早返回（Guard Clauses），避免超過三層的深層巢狀 `if/else`。
- 嚴禁將金鑰、存取憑證或環境機密直接寫入原始碼中。

2. 後端領域層與整潔架構 (.cursor/rules/backend-services.mdc)

此檔案僅在開發者修改服務層或領域業務程式碼時動態載入，避免上下文浪費。

---
description: 後端領域服務六邊形架構與倉儲模式約束
globs: src/services/**/*.ts, src/domains/**/*.ts
alwaysApply: false
---

# 後端領域架構規範

## 職責邊界劃分
- 控制器（Controller）負責 HTTP 請求反序列化、參數驗證與狀態碼封裝。
- 領域服務（Service）封裝純商業邏輯。嚴禁將 Express 或 Fastify 的 `req`/`res` 物件傳入服務層。
- 倉儲層（Repository）封裝資料存取。服務層必須依賴倉儲介面抽象，嚴禁直接相依具體 ORM 實例。

## 實作範例對比

```typescript
// ✅ 正確：服務層依賴抽象倉儲介面，處理純領域實體
export class OrderService {
  constructor(private readonly orderRepository: OrderRepositoryPort) {}

  async processOrder(orderId: string): Promise<Result<Order>> {
    const order = await this.orderRepository.findById(orderId);
    if (!order) return Result.fail('Order not found');
    order.markPaid();
    await this.orderRepository.save(order);
    return Result.ok(order);
  }
}

// ❌ 錯誤：商業邏輯中直接耦合 ORM 實例與資料庫更新
export class OrderService {
  async processOrder(orderId: string) {
    await prisma.orders.update({ where: { id: orderId }, data: { status: 'PAID' } });
  }
}

### 3. 單元與整合測試規範 (`.cursor/rules/testing-standards.mdc`)

此檔案規範 AI 產生單元測試時的框架選型與斷言風格。

```markdown
---
description: 單元測試與整合測試撰寫標準及驗證要求
globs: **/*.test.ts, **/*.spec.ts, src/tests/**/*
alwaysApply: false
---

# 自動化測試規範

## 測試技術棧
- 測試執行器：Vitest
- Mock 工具：`vi.mock()`（嚴禁混用 Jest 執行環境）
- 斷言庫：`expect()` 配合型別明確的 Matcher

## 測試結構與組織規範
- 嚴格遵循 Arrange-Act-Assert（安排-執行-斷言）三段式結構。
- 單元測試與受測原始碼存放於同目錄：如 `feature.service.ts` 對應 `feature.service.test.ts`。
- 嚴禁在單元測試中發起真實外部網路連線或存取真實資料庫，必須在邊界進行 Mock。
- 每次產生測試必須涵蓋負面邊界案例（如參數缺失、權限不足、系統拋出例外等）。

跨倉庫規模化治理：單體大倉與多倉同步架構

針對不同組織規模的儲存庫型態，團隊應採取分層的規則治理架構。

                          企業級規則治理體系
                                  │
         ┌────────────────────────┴────────────────────────┐
         ▼                                                 ▼
   單體大倉模式 (Monorepo)                         多倉庫模式 (Polyrepo)
  ├── .cursor/rules/00-core.mdc                  ├── 規則中心倉：org-cursor-rules
  ├── .cursor/rules/apps-web.mdc (依應用 Glob)    ├── CI/CD 自動化校驗與同步流程
  └── .cursor/rules/shared-ui.mdc (依模組 Glob)   └── Cursor Team Rules（後台統一管控）

模式一：單體大倉（Monorepo）的分級路徑約束

在基於 Turborepo、Nx 或 pnpm workspaces 的單體大倉中，所有規則均位於根目錄 .cursor/rules/，但透過細緻的 Glob 達成實體隔離：

• globs: ["apps/web/**/*"]：規範前端 Next.js 伺服器端元件（RSC）、樣式工具類別及狀態管理。
• globs: ["apps/api/**/*"]：規範後端 API 介面規格、OpenAPI 契約及資料庫遷移指令。
• globs: ["packages/ui/**/*"]：規範共用元件庫的語意化版本相容性、無障礙功能（ARIA）及避免第三方重型框架耦合。
• 治理成效： 開發者修改前端時，Cursor 不會載入後端資料庫規則，防止模型混淆架構邊界。

模式二：多程式碼倉庫的 CI/CD 程式碼化治理（Rules as Code）

針對微服務或分散式獨立倉庫，建議將 Cursor 規則視為版本化公共依賴套件進行維護：

1. 建立中央規則倉庫： 設立專用 Git 倉庫（例如 github.com/org/cursor-rules-standards），統一維護標準 .mdc 檔案，並以語意化標籤（如 v1.2.0）發布版本。
2. CI 漂移檢測機制： 在各微服務倉庫的 CI 流水線中加入檢驗任務，比對本地 .cursor/rules/ 是否與中央版本一致；若發現漂移則阻斷合併。
3. 自動化同步工作流： 透過 GitHub Actions 或自動化腳本，當中央規範發布新版時，自動向所有相關下游倉庫發起 Pull Request 進行更新。

模式三：企業級 Cursor Team Rules 中心管控

採用 Cursor Team 或 Enterprise 方案的企業團隊，可直接啟用官方原生集中管理能力：

• 儀表板統一下發： 管理員可在 Cursor 團隊管理後台統一設定組織級規則，設定會自動同步至所有已認證成員的開發環境中。
• 強制規範與彈性策略： 企業可將資安合規、授權宣告與技術選型底線設為「強制（Enforced）」，開發者無法在本地關閉；通用提示技巧可設為「可選（Optional）」，供成員視需求啟用。
• 跨倉即開即用： 開發者在全新複製的專案或不同工作機上作業時，均能自動繼承企業規範，大幅降低各專案重複維護配置的負擔。

實務建議與避坑指南

透過將 Cursor 規則建構為模組化、路徑精確對齊的 .mdc 規範樹，並輔以中央 Git 流水線或 Team Rules 治理機制，研發團隊能夠在享受 AI 輔助開發高效率的同時，確保架構模式與程式碼規範在所有倉庫中嚴格落實。

參考資料

• Cursor Docs — Agent, Rules, MCP, Skills & CLI
• Cursor Docs — Agent, Rules, MCP, Skills & CLI
• Cursor Docs — Agent, Rules, MCP, Skills & CLI