Claude Code 原始碼解讀：Plugin 架構與事件驅動的擴展生態系

Claude Code 是 Anthropic 推出的終端機 AI 程式設計工具。我們通常只看到它作為「命令列中的 AI 助手」，但深入它的開源倉庫，會發現一套設計精妙的 Plugin 架構——涵蓋 Commands、Agents、Skills、Hooks 四種元件類型、事件驅動的 Hook 攔截機制、以及自我迭代的 Ralph Loop 模式。閱讀這些原始碼，你能學到如何設計一個兼具安全性、可擴展性與自動化能力的 AI 工具生態系統。

Claude Code GitHub Repository — 專案原始碼，包含完整的 Plugin 系統設計與 13 個官方 Plugin 實作

專案概覽

Claude Code 是一個運行在終端機的 agentic coding tool，透過自然語言指令協助開發者執行日常編碼任務、解釋複雜程式碼、處理 git 工作流。專案以 Node.js 18+ 為基礎，主要語言是 Shell (56KB)、Python (38KB) 和 TypeScript (14KB)。開源倉庫包含 268 個檔案，核心是 13 個官方 Plugin 的完整實作與 Plugin 開發框架。

值得注意的是，Claude Code 的核心引擎（CLI 本體）並不在這個倉庫中——這裡是它的 Plugin 生態系統。這就像 VS Code 的 Extension API 一樣，真正的設計巧思藏在擴展機制裡。

架構總覽

claude-code/
├── .claude/commands/            # 倉庫自身使用的 Claude Code 指令
│   ├── commit-push-pr.md       # Git 工作流自動化
│   ├── dedupe.md               # Issue 重複檢測
│   └── oncall-triage.md        # On-call 問題分類
├── .claude-plugin/
│   └── marketplace.json        # Plugin 市場清單（13 個官方 Plugin）
├── .devcontainer/              # 沙箱化開發環境
│   ├── Dockerfile              # 容器定義
│   ├── devcontainer.json       # 環境設定
│   └── init-firewall.sh        # 網路防火牆白名單
├── .github/workflows/          # GitHub Actions 自動化
│   └── claude.yml              # @claude mention 觸發
├── examples/hooks/             # Hook 範例
├── plugins/                    # 13 個官方 Plugin
│   ├── hookify/               # 使用者自訂 Hook 引擎
│   ├── feature-dev/           # 功能開發 7 階段工作流
│   ├── code-review/           # 多 Agent 並行 Code Review
│   ├── pr-review-toolkit/     # PR 審查工具組
│   ├── security-guidance/     # 安全性提醒 Hook
│   ├── ralph-wiggum/          # 自我迭代迴圈
│   ├── frontend-design/       # 前端設計指引 Skill
│   ├── plugin-dev/            # Plugin 開發工具組
│   ├── explanatory-output-style/  # 教學風格 Hook
│   ├── learning-output-style/    # 學習模式 Hook
│   ├── commit-commands/       # Git 提交指令
│   ├── agent-sdk-dev/         # Agent SDK 開發工具
│   └── claude-opus-4-5-migration/ # 模型遷移工具
└── scripts/                    # Issue 管理自動化腳本
Code language: PHP (php)

核心設計解析

設計一：四元件 Plugin 架構——Commands、Agents、Skills、Hooks

Claude Code 的 Plugin 系統由四種互補元件組成，每種元件有不同的觸發方式和職責。這是整個生態系統的骨架。

plugins/plugin-dev/skills/plugin-structure/SKILL.md — Plugin 結構的完整規範，定義了四種元件的目錄慣例與自動發現機制

plugin-name/
├── .claude-plugin/
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Slash commands (.md files)
├── agents/                   # Subagent definitions (.md files)
├── skills/                   # Agent skills (subdirectories)
│   └── skill-name/
│       └── SKILL.md         # Required for each skill
├── hooks/
│   └── hooks.json           # Event handler configuration
├── .mcp.json                # MCP server definitions
└── scripts/                 # Helper scripts and utilities
Code language: PHP (php)

四種元件的設計哲學各不相同：

  • Commands：使用者主動觸發的 Slash 指令，以 Markdown + YAML Frontmatter 定義。設計為「使用者意圖的入口」
  • Agents：可被呼叫的子代理，具有獨立的 persona、工具權限和模型設定。設計為「可委派的專家」
  • Skills：Claude Code 根據任務情境自動啟用的知識模組，無需使用者手動觸發。設計為「隱性的領域知識」
  • Hooks：事件驅動的攔截器，在工具執行前後自動運行。設計為「系統層級的護欄」

這四者形成了從「使用者意圖」到「系統防護」的完整覆蓋。為什麼這樣設計？因為 AI 工具的擴展不只需要「新功能」，還需要「新約束」——Hooks 的存在就是讓使用者能在不修改核心程式碼的情況下添加安全規則和行為控制。

設計二：Markdown-as-Configuration——用 Prompt 當設定檔

整個 Plugin 系統最令人驚豔的設計，是幾乎所有元件都用 Markdown + YAML Frontmatter 來定義。Commands、Agents、Skills 全部是 .md 檔案——Prompt 本身就是設定檔。

plugins/feature-dev/agents/code-architect.md — 以 Markdown 定義一個具有完整 persona 的架構師 Agent

---
name: code-architect
description: Designs feature architectures by analyzing existing codebase patterns...
tools: Glob, Grep, LS, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, KillShell, BashOutput
model: sonnet
color: green
---

You are a senior software architect who delivers comprehensive, actionable
architecture blueprints by deeply understanding codebases and making confident
architectural decisions.

YAML Frontmatter 負責結構化的 metadata（名稱、工具權限、模型選擇），而 Markdown body 就是 System Prompt。這個設計有幾個深層意義：

  1. 降低 Plugin 開發門檻：你不需要寫 Python 或 TypeScript 來建立一個 Agent，只需寫 Markdown
  2. Prompt 即程式碼：在 AI-native 工具中，Prompt 的地位等同於程式碼。用 .md 儲存讓它可以 version control、code review、diff
  3. 自動發現機制：所有 commands/ 目錄下的 .md 檔案自動載入為指令，不需要額外的註冊步驟

設計三：事件驅動的 Hook 系統——九種生命週期事件

Hook 系統是整個架構中最具設計深度的部分。它定義了九種生命週期事件：PreToolUse、PostToolUse、Stop、SubagentStop、SessionStart、SessionEnd、UserPromptSubmit、PreCompact、Notification。

plugins/plugin-dev/skills/hook-development/SKILL.md — Hook 開發的完整指南，涵蓋所有事件類型和輸出格式

{
  "PreToolUse": [
    {
      "matcher": "Write|Edit|MultiEdit",
      "hooks": [
        {
          "type": "command",
          "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/security_reminder_hook.py"
        }
      ]
    }
  ]
}
Code language: JSON / JSON with Comments (json)

Hook 的設計遵循幾個關鍵原則：

  • Matcher 模式匹配：用 | 分隔多個工具名稱、* 匹配全部、正規表達式匹配 MCP 工具（如 mcp__.*__delete.*）
  • Exit Code 語意：0 表示成功、2 表示阻擋並將 stderr 回饋給 Claude、其他代碼為非阻擋錯誤
  • 並行執行：同一事件的所有匹配 Hook 並行運行，彼此看不到輸出，設計上要求 Hook 之間互相獨立
  • 兩種 Hook 類型：command 執行 shell 腳本做確定性檢查，prompt 使用 LLM 做語境感知判斷

設計四：Hookify 規則引擎——使用者可自訂的動態行為控制

Hookify 是一個「為 Hook 系統建立的 Hook」——它讓使用者通過 Markdown 檔案動態定義行為規則，而不需要寫程式碼。

plugins/hookify/core/rule_engine.py — 規則評估引擎，實作了條件匹配、優先級處理和多種 operator 支援

class RuleEngine:
    def evaluate_rules(self, rules: List[Rule], input_data: Dict[str, Any]) -> Dict[str, Any]:
        blocking_rules = []
        warning_rules = []

        for rule in rules:
            if self._rule_matches(rule, input_data):
                if rule.action == 'block':
                    blocking_rules.append(rule)
                else:
                    warning_rules.append(rule)

        # If any blocking rules matched, block the operation
        if blocking_rules:
            messages = [f"**[{r.name}]**\n{r.message}" for r in blocking_rules]
            combined_message = "\n\n".join(messages)
            # ...

RuleEngine 的核心設計：

  • Block > Warn 優先級：所有規則先全部評估，blocking 規則優先於 warning 規則
  • 多種 Operator：支援 regex_match、contains、equals、not_contains、starts_with、ends_with
  • LRU Cache 正規表達式編譯：用 @lru_cache(maxsize=128) 緩存已編譯的 regex pattern

plugins/hookify/core/config_loader.py — 規則檔案載入器，從 .claude/hookify.*.local.md 讀取 Markdown 格式的規則定義

規則定義延續了 Markdown-as-Configuration 的哲學。使用者只需建立一個 .claude/hookify.dangerous-rm.local.md：

---
name: warn-dangerous-rm
enabled: true
event: bash
pattern: rm\s+-rf
action: warn
---

⚠️ **Dangerous rm command detected**
You requested to be warned before using rm -rf.
Code language: JavaScript (javascript)

Config Loader 自行實作了一個簡易的 YAML parser，因為只需要處理 Frontmatter 的子集，不需要引入完整的 YAML 相依性——這是「最小相依」原則的體現。

設計五：多 Agent 協作的 Code Review 管線

Code Review Plugin 展示了如何用多個 Agent 建構可靠的審查管線，其中最有價值的設計是 信心分數過濾 機制。

plugins/code-review/commands/code-review.md — 多階段 Code Review 管線的完整 Prompt，定義了 Agent 分工和驗證流程

Review 管線共有 9 個步驟：

  1. 前置檢查（Haiku Agent）：確認 PR 不是 draft、未關閉、尚未被 review
  2. CLAUDE.md 收集（Haiku Agent）：找出所有相關的 CLAUDE.md 檔案路徑
  3. PR 摘要（Sonnet Agent）：理解變更內容
  4. 並行審查（4 個 Agent）：兩個 Sonnet 做 CLAUDE.md 合規檢查、兩個 Opus 做 bug 偵測
  5. 驗證階段（並行子 Agent）：為每個發現的問題啟動獨立 Agent 驗證是否為真正問題
  6. 過濾假陽性：移除未通過驗證的問題

7-9. 發佈 inline comments

Flag issues where:
- The code will fail to compile or parse
- The code will definitely produce wrong results regardless of inputs
- Clear, unambiguous CLAUDE.md violations

Do NOT flag:
- Code style or quality concerns
- Potential issues that depend on specific inputs or state
- Subjective suggestions or improvements
Code language: CSS (css)

這個設計的精髓在於「驗證階段」——每個問題都經過另一個 Agent 獨立驗證。這是一種 adversarial validation 模式：Review Agent 負責發現問題，Validation Agent 負責挑戰這些發現。這大幅減少了 false positives，因為 AI 審查最大的問題就是假陽性會侵蝕開發者信任。

設計六：Feature Development 的 7 階段工作流

Feature Development Plugin 展示了如何將軟體工程最佳實踐編碼為 AI 工作流。它的 7 個階段完整覆蓋了從需求到交付的全流程。

plugins/feature-dev/commands/feature-dev.md — 7 階段功能開發工作流的完整 Prompt 定義

## Phase 3: Clarifying Questions

**CRITICAL**: This is one of the most important phases. DO NOT SKIP.

**Actions**:
1. Review the codebase findings and original feature request
2. Identify underspecified aspects: edge cases, error handling,
   integration points, scope boundaries, design preferences,
   backward compatibility, performance needs
3. **Present all questions to the user in a clear, organized list**
4. **Wait for answers before proceeding to architecture design**

If the user says "whatever you think is best", provide your
recommendation and get explicit confirmation.
Code language: PHP (php)

這個設計的核心原則：

  • Clarifying Questions 被標記為 CRITICAL：Phase 3 明確要求在設計之前必須先釐清需求。這反映了一個深層洞察：AI 最容易犯的錯誤不是寫錯程式碼，而是解決錯誤的問題
  • Agent 分工明確：code-explorer 負責追蹤、code-architect 負責設計、code-reviewer 負責品質
  • 使用者控制點：Phase 4 要求使用者選擇架構方案，Phase 5 等待使用者明確批准才開始實作

設計七：安全 Hook 的 Pattern-Based 防護

Security Guidance Plugin 展示了如何用 Hook 機制為 AI 代理加上安全防護層。

plugins/security-guidance/hooks/security_reminder_hook.py — 安全提醒 Hook，檢測 9 種安全模式並在每個 session 只顯示一次

SECURITY_PATTERNS = [
    {
        "ruleName": "github_actions_workflow",
        "path_check": lambda path: ".github/workflows/" in path
            and (path.endswith(".yml") or path.endswith(".yaml")),
        "reminder": """You are editing a GitHub Actions workflow file.
        Be aware of these security risks:
        1. **Command Injection**: Never use untrusted input...
        2. **Use environment variables**: Instead of ${{ github.event... }}..."""
    },
    {
        "ruleName": "child_process_exec",
        "substrings": ["child_process.exec", "exec(", "execSync("],
        "reminder": """⚠️ Security Warning: Using child_process.exec()
        can lead to command injection vulnerabilities.
        This codebase provides a safer alternative:
        src/utils/execFileNoThrow.ts"""
    },
    # ... 7 more patterns
]
Code language: PHP (php)

安全 Hook 的設計巧思：

  • Session-scoped 去重：同一個 session 中，相同的 {file_path}-{rule_name} 組合只警告一次。用 JSON 檔案持久化 state，避免反覆打擾
  • 概率性清理：用 random.random() < 0.1 實現 10% 機率的 state 檔案清理，避免每次都做 I/O
  • Path-based + Content-based 雙重匹配：GitHub Actions 用路徑匹配（改 workflow 就觸發），其餘用內容子串匹配
  • Exit Code 2 阻擋模式：首次偵測到安全模式時用 exit code 2 阻擋工具執行，強迫 Claude 注意安全警告

設計八：Ralph Loop——自我迭代的永動機模式

Ralph Wiggum Plugin 是整個倉庫中最有創意的設計。它利用 Stop Hook 阻擋 Claude 的退出行為，將相同的 Prompt 重新送回，讓 Claude 在看到自己前一次工作成果的基礎上反覆迭代。

plugins/ralph-wiggum/hooks/stop-hook.sh — Stop Hook 腳本，攔截退出並將 Prompt 重新送入，實現自我迭代迴圈

# Read last assistant message from transcript (JSONL format)
LAST_LINE=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1)
LAST_OUTPUT=$(echo "$LAST_LINE" | jq -r '
  .message.content |
  map(select(.type == "text")) |
  map(.text) |
  join("\n")
')

# Check for completion promise (only if set)
if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
  PROMISE_TEXT=$(echo "$LAST_OUTPUT" | perl -0777 -pe \
    's/.*?<promise>(.*?)<\/promise>.*/$1/s; s/^\s+|\s+$//g; s/\s+/ /g')
  if [[ -n "$PROMISE_TEXT" ]] && [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
    echo "✅ Ralph loop: Detected <promise>$COMPLETION_PROMISE</promise>"
    rm "$RALPH_STATE_FILE"
    exit 0  # Allow exit
  fi
fi

# Not complete - continue loop with SAME PROMPT
jq -n --arg prompt "$PROMPT_TEXT" --arg msg "$SYSTEM_MSG" '{
    "decision": "block",
    "reason": $prompt,
    "systemMessage": $msg
}'
Code language: PHP (php)

Ralph Loop 的設計精髓：

  • Completion Promise 機制：透過 <promise> XML 標籤定義完成條件，只有當 Claude 輸出的 promise 內容「完全匹配」設定值時才允許退出。Prompt 中反覆強調「ONLY output when TRUE – do not lie to exit!」
  • State File 使用 Markdown Frontmatter：.claude/ralph-loop.local.md 同時存放狀態（YAML frontmatter 中的 iteration、max_iterations）和 Prompt（body），再次體現 Markdown-as-Configuration
  • 防腐化設計：腳本中有大量的 validation——檢查 state file 是否存在、iteration 是否為數字、transcript 是否可解析、assistant message 是否非空。任何異常都會清理 state file 並允許退出

設計九：SessionStart Hook 注入行為模式

Explanatory 和 Learning Output Style Plugin 展示了一種透過 SessionStart Hook 在 session 開始時注入 additionalContext 來改變 Claude 行為模式的技巧。

plugins/explanatory-output-style/hooks-handlers/session-start.sh — 透過 SessionStart Hook 注入教學模式的行為指引

cat << 'EOF'
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "You are in 'explanatory' output style mode...

    In order to encourage learning, before and after writing code,
    always provide brief educational explanations about implementation
    choices using:
    \"`★ Insight ─────────────────────────────────────`
    [2-3 key educational points]
    `─────────────────────────────────────────────────`\""
  }
}
EOF
Code language: PHP (php)

這個設計模式的巧妙之處在於：它不修改任何核心程式碼，而是在 session 的最開始就向 Claude 的 context 中注入額外的行為指引。這等於在不改動 System Prompt 的前提下，用 Hook 機制「裝飾」了 Claude 的行為——這是一種 Decorator Pattern 在 Prompt Engineering 中的應用。

設計十：沙箱化 DevContainer 的網路防火牆

DevContainer 配置展示了如何為 AI 編碼工具建構安全的沙箱環境。最核心的設計在 init-firewall.sh——它用 iptables 白名單嚴格限制容器的網路存取。

.devcontainer/init-firewall.sh — 防火牆初始化腳本，使用 iptables + ipset 實現嚴格的域名白名單

# Set default policies to DROP first
iptables -P INPUT DROP
iptables -P FORWARD DROP
iptables -P OUTPUT DROP

# Then allow only specific outbound traffic to allowed domains
iptables -A OUTPUT -m set --match-set allowed-domains dst -j ACCEPT

# Explicitly REJECT all other outbound traffic
iptables -A OUTPUT -j REJECT --reject-with icmp-admin-prohibited
Code language: PHP (php)

白名單僅包含：GitHub API/Web/Git、npm registry、Anthropic API、Sentry、StatsIG、VS Code Marketplace。腳本結尾還有驗證邏輯——確認 example.com 連不上但 api.github.com 連得上。

這個設計回答了一個關鍵問題：當你給 AI 執行 bash 指令的能力時，如何確保它不會存取不該存取的東西？ 答案是：不在應用層做限制，而是在網路層做白名單。

Prompt 設計解讀

Claude Code Plugin 系統中的 Prompt 設計有幾個值得學習的模式。

工具權限的精確控制

每個 Command 都在 Frontmatter 中用 allowed-tools 精確限定可用工具：

.claude/commands/commit-push-pr.md — Commit-Push-PR 指令，展示精確的工具權限控制

---
allowed-tools: Bash(git checkout --branch:*), Bash(git add:*),
  Bash(git status:*), Bash(git push:*), Bash(git commit:*),
  Bash(gh pr create:*)
description: Commit, push, and open a PR
---

注意 Bash(git checkout --branch:*) 這種格式——它不是簡單地允許 Bash，而是限制到特定的 git 子命令。這實現了 最小權限原則。

動態 Context 注入

Command 中使用 ! 前綴的 backtick 語法動態注入即時資訊：

## Context

- Current git status: !`git status`
- Current git diff: !`git diff HEAD`
- Current branch: !`git branch --show-current`
Code language: PHP (php)

這讓 Prompt 在每次執行時都攜帶最新的環境狀態，而不是靜態文字。

Agent 建立的元 Prompt

plugins/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md — Agent 生成功能使用的元 System Prompt，定義了如何設計 Agent 的 persona、指令和觸發條件

Agent 建立系統使用了一個精心設計的元 Prompt，指導 Claude 如何為新 Agent 撰寫 System Prompt。它要求生成的 Agent 配置包含三個部分：

{
  "identifier": "pr-quality-reviewer",
  "whenToUse": "Use this agent when...(含觸發範例)",
  "systemPrompt": "You are an expert...(完整行為指引)"
}
Code language: JSON / JSON with Comments (json)

其中的 whenToUse 部分特別要求包含 <example> 標籤的具體使用場景，這讓 Claude Code 能更精確地判斷何時自動啟用這個 Agent。

設計理念萃取

  • Markdown-as-Configuration 統一介面 — 在 AI-native 工具中，Prompt 就是程式碼。用 Markdown + YAML Frontmatter 統一所有元件定義，讓 Prompt 可以被 version control、code review、diff，同時將 Plugin 開發門檻降到「會寫 Markdown 就行」
  • 事件驅動的四層攔截 — Hook 系統涵蓋了從 Session 啟動到工具執行前後到退出的完整生命週期。九種事件讓你可以在任何時間點注入行為、驗證、阻擋或通知。這種設計讓安全性和品質控制不是事後補丁，而是架構內建的一等公民
  • Adversarial Validation 消除假陽性 — Code Review 管線中「Review Agent 找問題 → Validation Agent 驗證問題」的兩階段模式，是處理 AI 審查可靠性的關鍵策略。AI 的假陽性會侵蝕使用者信任，雙重驗證以信任換取時間
  • Decorator Pattern 做行為修飾 — 用 SessionStart Hook 注入 additionalContext 來改變 Claude 的輸出風格，不需要修改任何核心程式碼。這種模式讓行為客製化變成可組合的、可疊加的 Plugin
  • 網路層白名單比應用層限制更可靠 — 當你賦予 AI 執行 shell 指令的能力時，在應用層做限制容易被繞過。用 iptables + ipset 在網路層做白名單，是更根本的安全邊界

延伸思考

Claude Code Plugin 架構揭示了一個趨勢：AI 工具的擴展機制正在從「寫程式碼」轉向「寫 Prompt」。當你在建構自己的 AI 工具生態時，可以考慮以下應用方向：

Plugin 系統設計：如果你的 AI 應用需要擴展機制，參考四元件模型（Commands / Agents / Skills / Hooks），讓使用者可以透過 Markdown 定義新功能和行為約束。

安全護欄的實作：將 Security Hook 的 pattern matching + session-scoped dedup 模式應用到你的 AI agent 中，在工具執行前自動檢測已知的安全風險。

多 Agent 審查管線：為你的 AI 審查系統加入 adversarial validation 階段——讓一個 Agent 找問題，另一個 Agent 驗證問題。這比單一 Agent 的審查可靠得多。

自我迭代模式：Ralph Loop 的 Completion Promise 機制可以應用到任何需要迭代改進的場景——程式碼重構、文件撰寫、測試覆蓋率提升——讓 AI 在同一個任務上反覆精煉直到達標。

Vibe Coding：把觀念變成程式碼

以下是你可以直接給 AI 的 prompt 指令，將本文介紹的設計觀念應用到你的專案中：

Markdown-as-Configuration 定義 AI Agent

場景：你想為團隊建立可重複使用的 AI Agent，但不想寫複雜的程式碼框架

給 AI 的指令：

我想用 Claude Code 的 Markdown-as-Configuration 模式，為我的專案建立一個專門的 AI Agent。這個 Agent 的職責是 [描述職責，例如：審查 SQL 查詢的效能問題]。請幫我建立一個 .md 檔案，使用 YAML Frontmatter 定義 metadata（name、description、tools、model），Markdown body 作為 System Prompt。參考這個格式：Frontmatter 放結構化設定（名稱、可用工具清單、模型選擇），body 放完整的行為指引和專業知識。工具權限要遵循最小權限原則，只給這個 Agent 完成任務所需的工具。

效果：AI 會產出一個完整的 Agent 定義 Markdown 檔案，包含精確的工具權限控制和專業的 System Prompt，你可以直接放進 agents/ 目錄使用

事件驅動 Hook 攔截機制

場景：你想在 AI 執行特定操作前自動做安全檢查或品質控制，而不修改核心程式碼

給 AI 的指令：

請幫我設計一個 Claude Code Hook 系統，使用事件驅動的攔截機制。我需要在 [描述時機，例如：AI 要寫入檔案之前] 自動執行 [描述檢查，例如：檢查是否包含硬編碼的 API Key 或密碼]。請建立 hooks.json 配置和對應的 shell/python 腳本。Hook 設計要遵循以下原則：(1) 用 matcher 模式匹配精確指定要攔截的工具（如 “Write|Edit|MultiEdit”）；(2) 用 exit code 語意控制行為——exit 0 表示通過、exit 2 表示阻擋並回饋 stderr 給 AI；(3) 同一 session 中相同規則只觸發一次，避免重複打擾。

效果：AI 會產出可運作的 Hook 配置和腳本，實現 PreToolUse 事件的自動攔截，包含 pattern matching 和 exit code 處理邏輯

多 Agent Adversarial Validation 審查管線

場景：你想用 AI 做 Code Review 但擔心假陽性太多，需要更可靠的審查機制

給 AI 的指令：

請幫我設計一個多 Agent 協作的 Code Review 管線，參考 Claude Code 的 Adversarial Validation 模式。管線要包含：(1) Review Agent 負責找出 [描述審查重點，例如：潛在的 bug、效能問題、安全漏洞]；(2) Validation Agent 獨立驗證每個發現的問題是否為真正的問題；(3) 只保留通過驗證的問題。每個 Agent 用 Markdown 定義，明確區分角色——Review Agent 負責發現，Validation Agent 負責挑戰。審查標準要嚴格：只標記「一定會失敗」的問題，不標記風格偏好或主觀建議。這是為了避免假陽性侵蝕開發者對 AI 審查的信任。

效果：AI 會產出完整的多 Agent 審查管線定義，包含 Agent 分工、驗證流程、和假陽性過濾邏輯，可直接整合到 CI/CD 流程

Hookify 規則引擎——用 Markdown 定義行為約束

場景：你想讓團隊成員可以自行添加 AI 行為規則，而不需要寫程式碼

給 AI 的指令：

請幫我實作一個類似 Claude Code Hookify 的規則引擎。需求：(1) 規則用 Markdown + YAML Frontmatter 定義，放在 [指定目錄] 中自動載入；(2) 支援 block 和 warn 兩種 action，block 優先於 warn；(3) 支援 regex_match、contains、equals 等 operator 做條件匹配；(4) 用 LRU Cache 緩存編譯過的正規表達式提升效能。參考這個格式：Frontmatter 放 name、enabled、event、pattern、action，Markdown body 放顯示給使用者的訊息。Config Loader 只需處理 Frontmatter 子集，用自行實作的簡易 parser 即可，不需要引入完整的 YAML 依賴——這是最小相依原則。

效果：AI 會產出一個完整的規則引擎，包含 RuleEngine 類別、ConfigLoader、和範例規則檔案，團隊成員只需寫 Markdown 就能定義新的行為約束

SessionStart 注入的 Decorator Pattern

場景：你想改變 AI 的輸出風格或行為模式，但不想修改核心的 System Prompt

給 AI 的指令：

請幫我用 Decorator Pattern 的概念設計一個行為修飾機制。參考 Claude Code 的 SessionStart Hook 注入 additionalContext 模式：在 session 開始時，透過 Hook 向 AI 的 context 注入額外的行為指引，而不修改核心 System Prompt。我想要的行為模式是 [描述期望行為，例如：所有回覆都附上決策理由、每次修改程式碼前先說明設計考量]。請建立一個 SessionStart Hook 腳本，輸出包含 hookSpecificOutput.additionalContext 的 JSON。這個模式的好處是行為客製化變成可組合、可疊加的——多個 Hook 可以同時注入不同的行為指引。

效果：AI 會產出一個 SessionStart Hook 腳本，在每次 session 開始時自動注入行為指引，實現不修改核心程式碼的行為裝飾

Ralph Loop 自我迭代模式

場景：你有一個需要反覆改進的任務（重構、測試覆蓋率提升、文件完善），想讓 AI 自動迭代直到達標

給 AI 的指令：

請幫我設計一個 Ralph Loop 自我迭代機制。需求：(1) 用 Stop Hook 攔截 AI 的退出行為，將相同的 prompt 重新送回；(2) 實作 Completion Promise 機制——只有當 AI 輸出特定的 <promise>完成條件</promise> 標籤且內容完全匹配預設值時，才允許退出；(3) 用 state file 記錄 iteration 次數和 max_iterations，防止無限迴圈；(4) 加入防腐化設計——檢查 state file 存在性、iteration 是否為數字、transcript 是否可解析，任何異常都清理 state 並允許退出。我的迭代任務是 [描述任務，例如：持續重構直到所有函式的 cyclomatic complexity 低於 10]，完成條件是 [描述條件]。

效果：AI 會產出完整的 Stop Hook 腳本和 state file 模板，實現可控的自我迭代迴圈，包含安全的退出機制和狀態追蹤

延伸閱讀

0
標籤

相關文章

發佈留言

發佈留言必須填寫的電子郵件地址不會公開。 必填欄位標示為 *