Day 23｜System Prompt 統一管理的工具: ruler(二)

如果說 dotagent 為我們提供了模組化 System Prompt 管理的基礎能力，那麼 intellectronica/ruler 則在此基礎上更進一步，解決了我們在 Day 16 提到的「AI 不聽話」以及規則一致性驗證的問題。

ruler 的設計哲學是「apply the same rules to all coding agents」，它不僅提供統一的規則管理，更重要的是確保這些規則能夠有效地傳達給各種 AI 編程工具，並透過自動化機制保證規則的執行一致性。

一、ruler 專案概述與設計理念

1.1 解決的核心問題

在多 AI 工具的開發環境中，團隊面臨的挑戰包括：

• 不一致的指導：不同 AI 工具間的規則不統一
• 重複維護成本：需要維護多個配置檔案
• 上下文漂移：隨著專案需求演變，規則容易不同步
• 新工具導入困難：每次引入新 AI 工具都需要重新配置
• 複雜專案結構：不同元件需要不同的上下文特定指令

1.2 ruler 的解決方案

ruler 透過以下機制解決這些問題：

• 集中化規則管理：使用專門的 .ruler/ 目錄儲存所有 AI 指令
• 巢狀規則載入：支援複雜專案結構的上下文特定指令
• 自動分發機制：自動將規則套用到支援的 AI 代理工具配置檔案
• 精確代理配置：透過 ruler.toml 細調哪些代理受影響及其特定輸出路徑
• MCP 伺服器傳播：管理和分發 Model Context Protocol (MCP) 伺服器設定

1.3 支援的 AI 工具生態

ruler 支援範圍廣泛的 AI 編程工具：

二、ruler 的檔案結構與組織方式

2.1 基本目錄結構

ruler 使用簡潔的目錄結構來組織規則：

.ruler/
├── AGENTS.md           # 主要規則檔案
├── ruler.toml          # 主配置檔案
└── coding_style.md     # 額外的規則檔案

2.2 規則檔案的優先順序與合併機制

ruler 遵循明確的檔案優先順序：

1. 儲存庫根目錄的 AGENTS.md（最高優先級，會被前置）
2. .ruler/AGENTS.md（新的預設起始檔案）
3. 傳統的 .ruler/instructions.md（僅當 .ruler/AGENTS.md 不存在時）
4. 其餘在 .ruler/ 下的 *.md 檔案（按排序順序）

每個檔案的內容都會加上 --- Source: <relative_path_to_md_file> --- 標記以便追蹤。

2.3 規則檔案範例

基本規則檔案 (.ruler/AGENTS.md)：

# 專案開發規範

## 程式碼風格
- 遵循 PEP 8 規範（Python 專案）
- 使用類型提示標註所有函數簽名和複雜變數
- 保持函數簡短並專注於單一任務

## 錯誤處理
- 使用特定的異常類型而不是通用的 `Exception`
- 有效記錄錯誤並提供上下文資訊

## 安全性
- 始終驗證和清理使用者輸入
- 注意潛在的注入漏洞

專門化規則檔案 (.ruler/api_conventions.md)：

# API 設計約定

## RESTful API 設計
- 使用適當的 HTTP 動詞（GET, POST, PUT, DELETE）
- 回應狀態碼必須正確且一致
- API 端點命名使用複數名詞

## 資料驗證
- 所有輸入都必須使用 zod 進行驗證
- 錯誤回應格式必須統一
- 實作適當的速率限制

## 文件要求
- 每個 API 端點都必須有 OpenAPI 規範
- 包含請求/回應範例
- 標註必要的認證要求

三、巢狀規則載入：複雜專案的解決方案

3.1 巢狀規則的概念

ruler 的巢狀規則載入是其最強大的功能之一，特別適用於：

• 單一儲存庫多服務（Monorepos）
• 前後端分離的專案
• 需要不同區域不同指令的團隊
• 具有不同標準的複雜程式碼庫

3.2 巢狀規則的目錄結構範例

project/
├── .ruler/                 # 全域專案規則
│   ├── AGENTS.md
│   └── coding_style.md
├── src/
│   └── .ruler/             # 元件特定規則
│       └── api_guidelines.md
├── tests/
│   └── .ruler/             # 測試特定規則
│       └── testing_conventions.md
└── docs/
    └── .ruler/             # 文檔規則
        └── writing_style.md

3.3 巢狀規則的實際應用

啟用巢狀規則載入：

# 啟用巢狀載入，載入所有階層的 .ruler 目錄
ruler apply --nested

全域規則 (.ruler/AGENTS.md)：

# 專案整體開發規範

## 基本原則
- 程式碼必須清晰可讀
- 遵循 DRY 原則
- 適當的錯誤處理

## Git 提交規範
- 使用 Conventional Commits 格式
- 提交訊息必須是英文
- 包含適當的作用域標識

API 專用規則 (src/.ruler/api_guidelines.md)：

# API 開發特定規範

## 資料庫操作
- 使用 ORM 進行資料庫查詢
- 必須處理資料庫連線錯誤
- 實作適當的查詢最佳化

## 快取策略
- API 回應必須包含適當的快取標頭
- 使用 Redis 進行會話管理
- 實作智慧快取失效機制

測試專用規則 (tests/.ruler/testing_conventions.md)：

# 測試開發規範

## 測試結構
- 遵循 AAA 模式（Arrange, Act, Assert）
- 測試函數名稱必須描述性強
- 每個測試只驗證一個行為

## 測試覆蓋率
- 單元測試覆蓋率不低於 85%
- 關鍵業務邏輯必須 100% 覆蓋
- 包含邊界條件測試

## Mock 使用
- 優先使用測試替身而非真實服務
- Mock 物件的行為必須與真實物件一致
- 避免過度 Mock 導致測試失去意義

四、ruler 的安裝與基本操作

4.1 安裝方式

全域安裝（推薦用於 CLI）：

npm install -g @intellectronica/ruler

使用 npx（一次性命令）：

npx @intellectronica/ruler apply

4.2 專案初始化

基本初始化：

# 導航到專案根目錄
cd your-project

# 初始化 ruler
ruler init

這會建立：

• .ruler/ 目錄
• .ruler/AGENTS.md：主要規則檔案
• .ruler/ruler.toml：配置檔案

全域配置初始化：

# 建立全域配置，當找不到本地 .ruler/ 目錄時使用
ruler init --global

全域配置將建立在 $XDG_CONFIG_HOME/ruler（預設：~/.config/ruler）。

4.3 套用規則到 AI 代理工具

基本套用命令：

# 套用規則到所有配置的代理工具
ruler apply

# 只套用到特定代理工具
ruler apply --agents copilot,claude

# 使用巢狀規則載入
ruler apply --nested

# 預覽變更而不實際寫入檔案
ruler apply --dry-run

# 詳細輸出模式
ruler apply --verbose

常用套用選項：

五、ruler.toml 配置檔案詳解

5.1 基本配置結構

ruler.toml 是 ruler 行為的主要控制檔案：

# 預設執行的代理工具
default_agents = ["copilot", "claude", "aider"]

# 全域 MCP 伺服器配置
[mcp]
enabled = true
merge_strategy = "merge"

# MCP 伺服器定義
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]

[mcp_servers.git]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-git", "--repository", "."]

# 自動 .gitignore 配置
[gitignore]
enabled = true

# 代理工具特定配置
[agents.copilot]
enabled = true
output_path = ".github/copilot-instructions.md"

[agents.claude]
enabled = true
output_path = "CLAUDE.md"

[agents.cursor]
enabled = true
output_path = ".cursor/rules/ruler_cursor_instructions.mdc"

[agents.windsurf]
enabled = false  # 停用特定代理工具

5.2 MCP 伺服器配置

ruler 支援管理 Model Context Protocol (MCP) 伺服器設定，這為 AI 模型提供更廣泛的上下文：

本地/stdio 伺服器配置：

[mcp_servers.local_server]
command = "node"
args = ["server.js"]

[mcp_servers.local_server.env]
DEBUG = "1"
API_KEY = "your-api-key"

遠端伺服器配置：

[mcp_servers.remote_server]
url = "https://api.example.com"

[mcp_servers.remote_server.headers]
Authorization = "Bearer token"
"X-API-Version" = "v1"

5.3 代理工具專用 MCP 配置

可以為特定代理工具設定不同的 MCP 行為：

# Cursor 特定的 MCP 配置
[agents.cursor.mcp]
enabled = true
merge_strategy = "merge"

# 覆寫策略替代合併策略
[agents.claude.mcp]
enabled = true
merge_strategy = "overwrite"

六、回復機制：安全的實驗環境

6.1 ruler revert 命令

ruler 提供了完整的回復機制，讓團隊可以安全地實驗不同的配置：

# 回復所有 ruler 變更
ruler revert

# 預覽會被回復的內容
ruler revert --dry-run

# 只回復特定代理工具
ruler revert --agents claude,copilot

# 回復後保留備份檔案
ruler revert --keep-backups

6.2 備份機制

ruler 在覆寫任何現有檔案之前會自動建立 .bak 備份：

• 智慧還原：從備份檔案還原時優先使用 .bak 檔案
• 清除生成檔案：移除之前不存在的 ruler 生成檔案
• 選擇性清理：可以選擇只移除特定代理工具的配置

七、自動 .gitignore 管理

7.1 自動化版本控制管理

ruler 自動管理 .gitignore 檔案，確保生成的代理工具配置檔案不會被意外提交：

# Your existing rules
node_modules/
*.log

# START Ruler Generated Files
.aider.conf.yml
.clinerules
.cursor/rules/ruler_cursor_instructions.mdc
.github/copilot-instructions.md
.windsurf/rules/ruler_windsurf_instructions.md
AGENTS.md
CLAUDE.md
# END Ruler Generated Files

dist/

7.2 .gitignore 管理控制

# 啟用/停用 .gitignore 自動更新
ruler apply --no-gitignore

# 在 CI/CD 中使用時避免修改 .gitignore
ruler apply --no-gitignore

八、團隊協作最佳實踐

8.1 專案整合工作流程

1. 團隊規範建立：

# 建立團隊共用的規則檔案
mkdir -p .ruler
cat > .ruler/AGENTS.md << 'EOF'
# 團隊開發規範

## 程式碼品質標準
- 所有函數都必須有文檔字串
- 使用類型提示提高程式碼可讀性
- 遵循專案的命名約定

## 測試要求
- 新功能必須包含測試
- 測試覆蓋率維持在 80% 以上
- 使用描述性的測試名稱
EOF

# 套用到所有代理工具
ruler apply

2. 版本控制整合：

# 將 .ruler 目錄提交到儲存庫
git add .ruler/
git commit -m "feat: add team AI coding standards with ruler"

# 團隊成員拉取變更後套用配置
git pull
ruler apply

3. package.json 腳本整合：

{
  "scripts": {
    "ruler:apply": "ruler apply",
    "dev": "npm run ruler:apply && your_dev_command",
    "precommit": "npm run ruler:apply"
  }
}

8.2 大型專案的巢狀規則策略

Monorepo 的巢狀規則組織：

# 建立服務特定的規則
mkdir -p services/api/.ruler
cat > services/api/.ruler/api_standards.md << 'EOF'
# API 服務開發規範

## 資料庫操作
- 使用連線池管理資料庫連線
- 實作適當的查詢超時
- 記錄慢查詢用於效能監控

## API 設計
- 遵循 REST 原則
- 實作適當的錯誤處理
- 包含 API 版本管理
EOF

mkdir -p services/frontend/.ruler
cat > services/frontend/.ruler/frontend_standards.md << 'EOF'
# 前端開發規範

## React 最佳實踐
- 使用函數式元件和 Hooks
- 實作適當的錯誤邊界
- 優化組件重新渲染

## 狀態管理
- 使用 Redux Toolkit 進行狀態管理
- 實作適當的資料正規化
- 避免不必要的狀態提升
EOF

# 套用巢狀規則
ruler apply --nested --verbose