Agent Rules：讓 AI 程式助手變得更聰明的開源規則庫

🎯 專案簡介

Agent Rules 是一個由 Peter Steinberger 開發的開源專案，專門為 AI 程式設計助手（如 Claude Code、Cursor 等）提供可重複使用的規則和知識庫。這個專案的核心理念是透過標準化的規則檔案，讓 AI 助手能夠更準確地理解開發者的意圖，並產生符合專案需求的程式碼。

            💡 核心價值：將 AI 助手從「聰明的自動完成工具」提升為「懂得專案規範的開發夥伴」
        

🚀 開發動機：解決 AI 助手的「失憶症」

在 AI 程式設計助手快速發展的今天，開發者們發現了一個共同的痛點：AI 助手雖然聰明，但缺乏專案脈絡和團隊規範的記憶。

主要痛點分析

🧠 記憶缺失問題

每次新的對話，AI 就像新進員工一樣，不記得之前的規範和偏好

📝 重複說明浪費時間

開發者必須反覆告訴 AI 相同的程式碼風格和架構偏好

🎯 缺乏一致性

不同的 AI 工具產生的程式碼風格不一致，需要人工修正

🔧 工具切換困難

從 Cursor 換到 Claude Code 時，規則無法通用，重新設定麻煩

            Peter Steinberger 在部落格中提到：「就像每天都有新員工報到一樣，你必須不斷地向 AI 解釋相同的規則和慣例。」
        

🛠️ 解決方案：統一的規則格式

Agent Rules 透過 .mdc（Markdown with Configuration）格式，創造了一個跨平台的解決方案：

📄 .mdc 檔案結構範例

--- YAML 前置資料（供 Cursor 使用）---
description: "標準化的 commit 訊息格式"
globs:
  - "**/*.{js,ts,py,go}"
alwaysApply: true
---

# Commit 規則（Markdown 內容供 Claude Code 使用）

當執行 commit 操作時，請遵循以下規範：

## 📝 Commit 訊息格式
- 使用 type(scope): description 格式
- 支援 emoji 表達類型
- 限制首行 50 字元以內

## 🏷️ 類型標籤
- feat: ✨ 新功能
- fix: 🐛 錯誤修復  
- docs: 📚 文件更新
- refactor: ♻️ 程式碼重構
            

🎮 使用情境：從個人到企業級應用

情境一：個人專案快速設定

🚀 快速啟動流程

# 1. 複製規則檔案到專案
cp agent-rules/project-rules/commit.mdc .cursor/rules/

# 2. Cursor 自動套用規則
# 當你修改任何 JS/TS 檔案時，AI 就會依照規則產生 commit

# 3. Claude Code 全域設定
mkdir -p ~/.claude
echo "@import agent-rules/project-rules/commit.mdc" >> ~/.claude/CLAUDE.md
            

情境二：團隊協作標準化

👥 團隊設定範例

# 團隊專案的 .cursor/rules/ 目錄結構
.cursor/rules/
├── commit.mdc           # 統一 commit 格式
├── pr-review.mdc        # PR 審查清單
├── code-analysis.mdc    # 程式碼品質檢查
└── bug-fix.mdc          # 錯誤修復流程

# 每個團隊成員的 AI 助手都會自動遵循相同規則

情境三：企業級 CI/CD 整合

🏢 企業應用場景

# GitHub Actions 工作流程
name: "AI Code Review"
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-review:
    runs-on: ubuntu-latest
    steps:
      - name: "Checkout code"
        uses: actions/checkout@v3
      
      - name: "Run AI Code Analysis"
        run: |
          # 使用 Agent Rules 中的分析規則
          claude-code --rules-file .cursor/rules/code-analysis.mdc \
                     --analyze-diff HEAD~1..HEAD
            

🎯 適用場景

前端開發

後端 API

DevOps

行動應用

機器學習

🛠️ 支援工具

Claude Code

Cursor

GitHub Copilot

Windsurf

📊 團隊規模

個人專案

小型團隊

中型企業

大型組織

🔧 實際應用範例

範例 1：自動化 Bug 修復流程

--- bug-fix.mdc 規則檔案 ---
description: "完整的錯誤修復工作流程"
globs: ["**/*"]
alwaysApply: true
---

# 🐛 Bug 修復標準流程

## 1️⃣ 問題分析階段
- 重現錯誤並記錄步驟
- 檢查相關的測試案例
- 分析錯誤日誌和堆疊追蹤

## 2️⃣ 解決方案設計
- 找出根本原因（不只是症狀）
- 考慮對其他功能的影響
- 設計最小化的修改方案

## 3️⃣ 實作與測試
```javascript
// 修復前：添加詳細註解說明問題
// BUG: 當 user.email 為 null 時會造成系統崩潰
function sendEmail(user) {
  return emailService.send(user.email, message);
}

// 修復後：加入防護檢查
function sendEmail(user) {
  if (!user?.email) {
    throw new Error('User email is required');
  }
  return emailService.send(user.email, message);
}
```

## 4️⃣ 品質確保
- 撰寫針對此錯誤的測試案例
- 確認相關功能正常運作
- 更新文件說明修復內容
        

範例 2：Swift 專案現代化規則

--- swift-observable.mdc 規則檔案 ---

# 🍎 Swift Observable 遷移指南

## 從 ObservableObject 升級到 @Observable

### ❌ 舊寫法 (ObservableObject)
```swift
import SwiftUI
import Combine

class UserStore: ObservableObject {
    @Published var username: String = ""
    @Published var isLoggedIn: Bool = false
    
    func login() {
        // 登入邏輯
        isLoggedIn = true
    }
}
```

### ✅ 新寫法 (@Observable)
```swift
import SwiftUI

@Observable
class UserStore {
    var username: String = ""
    var isLoggedIn: Bool = false
    
    func login() {
        // 登入邏輯 - 自動觸發 UI 更新
        isLoggedIn = true
    }
}

// 在 SwiftUI View 中使用
struct ContentView: View {
    @State private var userStore = UserStore()
    
    var body: some View {
        VStack {
            Text(userStore.username)
            Button("Login") {
                userStore.login()
            }
        }
    }
}
```

## 🎯 遷移重點
- 移除 @Published 屬性包裝器
- 使用 @Observable 標記類別
- 在 SwiftUI 中改用 @State 替代 @StateObject
        

範例 3：MCP 伺服器自動設定

--- mcp-peekaboo-setup.mdc 全域規則 ---

# 📸 Peekaboo MCP 伺服器自動設定

## 🚀 一鍵安裝腳本
```bash
#!/bin/bash

# 檢查系統需求
echo "🔍 檢查系統需求..."
command -v node || echo "❌ 需要 Node.js 20.0+"
command -v jq || brew install jq

# 安全地從 ~/.zshrc 提取 API 金鑰
OPENAI_KEY=$(grep "OPENAI_API_KEY" ~/.zshrc | 
              cut -d'=' -f2 | 
              tr -d '"'")

# 設定 Claude MCP 伺服器
echo "⚙️  設定 Peekaboo MCP 伺服器..."
claude mcp add-json -s user peekaboo '{
  "command": "npx",
  "args": ["-y", "@steipete/peekaboo-mcp@beta"],
  "env": {
    "OPENAI_API_KEY": "'"${OPENAI_KEY}"'",
    "LOG_LEVEL": "INFO"
  }
}'

echo "✅ Peekaboo 設定完成！現在可以讓 AI 分析螢幕截圖了"
```

## 🎯 功能特色
- **視覺 AI 分析**：AI 可以「看」螢幕截圖並提供建議
- **雙 AI 引擎**：支援 OpenAI 和 Ollama
- **安全設計**：API 金鑰安全提取和儲存
- **即裝即用**：無需複雜設定

## 📱 使用案例
- UI/UX 設計審查
- 錯誤畫面診斷  
- 自動化測試驗證
- 程式碼審查輔助
        

💡 最佳實踐建議

🎯 規則設計原則

保持規則簡潔明確
使用具體的範例說明
避免過度複雜的巢狀邏輯
定期更新和維護規則

🔧 工具整合技巧

善用 YAML 前置資料控制範圍
配合 MCP 伺服器增強功能
建立團隊共用規則庫
版本控制規則檔案變更

⚡ 效能最佳化

使用精確的 glob 模式
避免過度啟用的全域規則
定期清理不用的規則檔案
監控 AI 響應時間變化

🚀 開始使用 Agent Rules

📦 快速安裝

# 1. 複製專案
git clone https://github.com/steipete/agent-rules.git

# 2. 設定 Cursor 專案規則
mkdir -p .cursor/rules
cp agent-rules/project-rules/*.mdc .cursor/rules/

# 3. 設定 Claude Code 全域規則
mkdir -p ~/.claude
cp agent-rules/global-rules/github-issue-creation.mdc ~/.claude/CLAUDE.md

# 4. 開始享受智能 AI 協作！
cursor .  # 或 claude-code
            

            🌟 立即體驗：安裝完成後，嘗試修改任何程式檔案，你會發現 AI 助手突然變得「很懂你的需求」！
        

🚀 前往 GitHub 專案頁面

🔮 未來展望

Agent Rules 代表了 AI 輔助程式設計的重要里程碑。它將 AI 助手從簡單的自動完成工具，提升為真正理解專案脈絡的智能夥伴。

🎯 社群生態

越來越多開發者貢獻規則，形成豐富的知識庫生態系統

🔧 工具整合

更多 AI 開發工具將支援 .mdc 格式，實現真正的跨平台通用

🚀 自動化程度

結合 CI/CD 管線，實現從程式碼撰寫到部署的全自動化流程

正如 Peter Steinberger 所說：「我們正處於軟體開發典範轉移的時代，AI 代理人將成為我們最重要的開發夥伴。」Agent Rules 正是這個轉變的催化劑，讓每一位開發者都能擁有一個懂得專案規範、遵循最佳實踐的 AI 助手。