寫一個禮拜的 Claude Code 你會發現一件事：你一直在重複貼類似的提示。

「幫我寫個 conventional commit」、「用 Five Whys 找根因」、「幫我審 PR 邊界條件」、「先寫 failing test 再修」——每天從零開始打一遍，品質還飄。

agent-rules 解的就是這個。它的觀點很單純：prompt 不該每次重打，prompt 該被當成設定檔。

5.7k stars / 514 forks，是目前 Claude Code 規則集合裡名氣最大的之一。作者 Peter Steinberger 是 PSPDFKit 創辦人，習慣把工程紀律寫死成可執行的東西。這個 repo 把工程師日常會反覆下的提示，整理成 22 個 markdown 檔案，丟進 ~/.claude/commands/，之後在 Claude Code 裡打 /commit、/bug-fix、/pr-review 就會跑。

跟 Linux command 同一個直覺。

為什麼這件事不顯而易見

大部分人用 AI 寫 code 的工作流是這樣的：開 chat、貼程式碼、口頭描述任務、等回應、修一輪、再修一輪。每一輪都要把上下文跟期望重新講一遍。

這跟「每次煮飯都從頭背一遍食譜」沒兩樣。

把食譜寫在牆上，按一下就跑——這個動作的價值不在「省幾秒打字」，在於每次跑的版本是同一個版本。你不會今天 commit message 偷懶不寫 scope、明天又加上去；不會這次 bug fix 忘了先寫 failing test、下次又補回來。工程紀律的關鍵不是「我懂這個道理」，是「我每次都會做」。

把這層紀律從你的腦袋移到 markdown 檔，agent 才會穩定執行。

agent-rules 本質不是 framework，不是函式庫，是精煉過的 prompt 範本庫。

倉庫結構：三層各自負責一件事

整個 repo 設計成三層，各自做不同等級的事：

層級 用途 安裝位置
project-rules/ 22 個可重用的 slash command（commit / bug-fix / pr-review 等） ~/.claude/commands/ 或 .cursor/rules/
global-rules/ 帳號層級的設定：MCP server 安裝腳本、issue 模板、terminal title 工具 ~/.claude/CLAUDE.md、shell rc
docs/ Swift / Apple 領域的大型參考文件（appkit / swiftui / uikit 各百萬字） 按需 import

核心是 project-rules/，22 個 .mdc 檔案撐起整個工作流的體驗。

為什麼用 .mdc 副檔名（這是個小細節，但很聰明）

.mdc 本來是 Cursor 的 rules 格式：純 markdown 加上 YAML frontmatter，可以宣告 description、globs、alwaysApply：

1
2
3
4
5
---
description: Clear, one-line description of what the rule enforces
globs: path/to/files/*.ext, other/path/**/*
alwaysApply: false
---

Claude Code 沒有這個概念，但它把 .mdc 當成普通 markdown 讀，所以同一份檔案可以同時餵給 Cursor 跟 Claude Code。

跨工具兼容的第一步不是寫適配器，是選對副檔名。這個觀察應用到自己的規則庫上，可以省掉很多重複維護。

22 個指令選四類有代表性的看

Git & GitHub

指令 用途
/commit 完整版：跑 pre-commit checks、偵測 commit type、用 emoji + conventional 格式產出訊息、建議拆 commit
/commit-fast 快速版：生成 3 個訊息候選並自動採用第一個
/bug-fix 全流程：建 issue → 開 branch → 寫 failing test → 修 → push → 開 PR（含 Fixes #N）
/pr-review 6 種 persona 同時審：PM / Dev / QA / Security / DevOps / UX
/analyze-issue 用 gh issue view 抓 issue，輸出 10 段技術 spec

Code Quality

指令 用途
/check 跑 quality gate。明文禁止 commit、禁止改版號，純驗證
/clean 跑 formatter + type checker 修到全綠
/code-analysis 6 種分析菜單：knowledge graph / quality / performance / security / architecture / coverage

Development Workflow

指令 用途
/implement-task 5 階段方法論：think strategy → evaluate → tradeoffs → implement → checklist
/context-prime 讀 README、CLAUDE.md、git ls-files，建立對陌生專案的初步理解
/five Five Whys 根因分析：鏈式追問五次直到 root cause
/mermaid 從 SQL / source code 抽實體與關係，輸出 mermaid 圖並用 mmdc 驗證

Meta（規則自己進化）

指令 用途
/create-command 用 agent 幫你寫新的 slash command（meta-bootstrap）
/continuous-improvement 觀察 codebase 的 pattern，當某個模式出現 3 次以上就建議寫成新規則
/cursor-rules-meta-guide 規範 .mdc 應該怎麼寫（含 DO / DON’T 對照範例）

安裝：兩個指令解決

1
2
3
4
5
6
# 1. clone repo
git clone https://github.com/steipete/agent-rules
cd agent-rules

# 2. 跑安裝腳本
./install-project-rules.sh

腳本做的事很單純：在 ~/.claude/CLAUDE.md 加一行 @<repo_path>/project-rules，靠 Claude Code 的 import 語法把 22 個 .mdc 全部納入。裝完直接打 /commit、/bug-fix 就能用。

給 Cursor 的話，.mdc 本來就是 Cursor 的原生格式，把 project-rules/ 整個丟進專案的 .cursor/rules/ 就好。

真正值得偷的不是指令，是五個設計手法

讀完 22 個規則之後，會發現有些手法可以直接抄到自己的規則集裡。這部分比指令本身更有複利價值。

1. 二段式工作流（完整版 vs 快速版）

commit.mdc 跟 commit-fast.mdc 是同一件事的兩種精度。完整版做安全把關（lint、pre-commit hook、拆 commit 建議），快速版省掉互動直接出 3 個訊息選一個。

同一個任務做兩個版本，依場合切換。趕時間用 fast，要進 production 用完整版。這個 pattern 套到自己的規則集很實用——/test-quick vs /test-thorough、/review-self vs /review-team。

2. 多 persona 自我審查

pr-review.mdc 用 6 個角色同時看一段 PR：

  • PM：功能符合需求嗎？
  • Dev：code quality 與架構合理嗎？
  • QA：測試覆蓋率與邊界條件？
  • Security：資安漏洞？
  • DevOps：部署與監控影響？
  • UX：使用者體驗變化？

比起單一視角的 reviewer，這種「多角色同步檢視」能撈出更多問題。LLM 在角色切換上其實很順——你給它一個角色 + 一個任務，它就會用那個角色的優先序看事情。可以直接借用這個 prompt 結構，連 persona 都不用改。

3. 強制紀律：把禁區寫在最前面、用大寫

/check 規則開頭寫死：

DO NOT commit. DO NOT change version numbers. Only verify.

mcp-inspector-debugging.mdc 開頭警告：

DO NOT RUN BLOCKING TERMINAL COMMANDS

這比寫一堆解釋有用。LLM 容易越界做副作用，最有效的方法就是在指令最前面用大寫寫死禁區。寫散文式的引導 LLM 容易自己腦補；寫成大寫禁令它會當作 hard constraint。

這個觀察對寫任何 prompt 都適用——你想阻止 AI 做某件事，與其解釋為什麼不該做，不如直接禁止它做。

4. 編號流程化

所有規則都遵循固定骨架：

1
2
3
4
5
6
7
8
9
# Title
One-line description

## Usage
## Process
  1. Step one
  2. Step two
  3. Step three
## Best Practices

寫散文 LLM 容易漏步驟，全部拆成編號讓它逐條執行，準確度差很多。

這也是寫文件的反直覺：人類讀者喜歡散文，但你的目標讀者是 LLM。LLM 喜歡編號。

5. self-evolving 機制

continuous-improvement.mdc 規定：當 agent 在你的 codebase 觀察到某個 pattern 出現 3 次以上，就主動建議把它寫成新規則。/create-command 直接用 agent 幫你產生新指令的骨架。

把規則集當成「會自己進化的東西」來設計，而不是寫完就鎖死的靜態文件。這個視角差異會決定你的規則庫一年後是更精煉還是更笨重。

實際應用情境

每日 commit 加速

寫完功能不用想 commit message 怎麼寫，直接打 /commit-fast 就會自動偵測檔案性質、選 type、加 emoji、產 conventional 格式。一天省幾分鐘，一個月省半小時。

修 bug 走完整流程

碰到 bug 別急著改 code，先打 /bug-fix。它會引導：建 issue → 開 fix/xxx branch → 先寫能重現的 failing test → 實作修復 → push → 開 PR 連動 issue。整個 TDD 流程被規則化，不會省略寫測試這一步。

PR 送審前自我檢查

要送 PR 給 reviewer 之前先跑 /pr-review，六個 persona 自己先打過一遍。比起拿給人看再被打回來，效率高很多。

接手陌生 codebase

第一次進新專案，打 /context-prime。agent 會讀 README、CLAUDE.md、git ls-files 給一份結構摘要，比自己 tree 半天有效率。

把模糊需求變成技術 spec

業務丟一個 issue 連結過來只有兩句話描述，打 /analyze-issue <issue#>，agent 用 gh issue view 抓回來，產出 10 段式技術規格（要改哪些檔案、要新建哪些檔案、out of scope、success criteria）。

畫架構圖

要產 ER diagram 或 sequence diagram，丟 schema 或 code 給 /mermaid，輸出可驗證的 mermaid 語法，還會用 mmdc 確認語法正確。比手畫快太多。

但是有些限制要知道

作者已停止積極維護。README 明示這是 2025 年中的舊作，新工作在 steipete/agent-scripts。把這個 repo 當作學習範本可以；當長期相依套件要三思。

其他幾個踩坑點：

  • 不少規則是 macOS 專用：safari-automation、screenshot-automation、mcp-peekaboo-setup、terminal-title-wrapper 在 Linux / Windows 跑不起來
  • docs/ 巨型檔案會吃 context：appkit.md（2.3MB）、swiftui.md（1.8MB）這種等級的文件直接 alwaysApply 會炸 context window，建議按需 import
  • 強綁定作者的 MCP 生態：推薦的 Peekaboo / Agent / Automator 都是 @steipete 自己發的 npm 套件，用之前自己評估信任邊界
  • commit 規則內建 emoji：對禁用 emoji 的企業 commit convention 不友善，要自己改規則
  • **/check 假設專案有 npm run check**：其他語言沒提供 fallback，要自己改

適合誰用：

  • 把 Claude Code 或 Cursor 當主要 AI pair programmer 的工程師
  • 想自己寫 .mdc 規則但缺範本參考的人
  • macOS / iOS / Swift 開發者（docs/ 對你最有用）
  • 對「prompt as config」這個觀念有興趣、想看精煉範例的人

不適合：

  • 只用 GitHub Copilot、完全不用 Claude Code / Cursor 的人
  • 純 Linux / Windows 開發者（一半 automation 規則跑不起來）
  • 期待持續更新與社群維護的人（請改追 agent-scripts）

收尾：背後的兩條線

agent-rules 的價值不在 22 個指令本身，在它把兩件事示範清楚了。

第一條線：prompt 不是文字，prompt 是設定檔。 一旦你接受這個觀念，你就會開始把所有反覆寫的提示都抽出來、放進版本控管、加上 review 流程。這個轉變對工程紀律的影響，比換一個更新的模型還大。

第二條線：規則庫應該會自己長大。 寫完就鎖死的規則庫只會越用越過時。把 /create-command 跟 /continuous-improvement 放進規則集裡，等於讓規則庫變成一個會觀察、會建議的東西。

挑一個你最常下的 prompt，寫成 .mdc 丟進 ~/.claude/commands/，明天打那個 slash 試試看。比你以為的還順。

相關連結